# What is Archera?

Cloud cost optimization platform that reduces spending by 20-30% through intelligent commitment management

Archera is a **free cloud cost optimization platform** that helps organizations reduce their cloud spending by **20-30%** through intelligent commitment management across AWS, Azure, and Google Cloud.

### ​The Problem We Solve <a href="#the-problem-we-solve" id="the-problem-we-solve"></a>

Cloud costs are spiraling out of control for most organizations:

* **On-demand pricing** is the most expensive way to run cloud infrastructure
* **Native commitment tools** are complex, risky, and lack flexibility
* **Multi-cloud management** requires juggling multiple cost tools and strategies
* **Long-term commitments** (1-3 years) create risk when business needs change

### ​How Archera Helps <a href="#how-archera-helps" id="how-archera-helps"></a>

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Intelligent Optimization</strong></td><td><p><strong>AI-Powered Analysis</strong></p><ul><li>Analyzes your actual usage patterns</li><li>Identifies optimal commitment strategies</li><li>Provides risk-adjusted recommendations</li><li>Continuously optimizes over time</li></ul></td></tr><tr><td><strong>Risk Protection</strong></td><td><p><strong>Guaranteed Commitments</strong></p><ul><li>30-day minimum terms (vs 1-3 years native)</li><li>Downside Protection</li><li>Insurance against underutilization</li><li>Transfer flexibility between accounts</li></ul></td></tr><tr><td><strong>Multi-Cloud Unity</strong></td><td><p><strong>Unified Management</strong></p><ul><li>Single platform for all cloud providers</li><li>Cross-cloud optimization strategies</li><li>Consolidated reporting and analytics</li><li>Simplified cost governance</li></ul></td></tr></tbody></table>

### ​Who Uses Archera? <a href="#who-uses-archera" id="who-uses-archera"></a>

<details open>

<summary>Direct Customers</summary>

**Organizations optimizing their own cloud costs**

Use Archera’s free platform to analyze your cloud spending, get intelligent recommendations, and implement risk-free commitments with flexible terms.

</details>

<details open>

<summary>Channel Partners</summary>

**Partners managing multiple customer organizations**

Use the Partner API to onboard customers, manage their optimization strategies, and create marketplace offers through programs like AWS CPPO, Microsoft MPO or ISV-to-CSP Private Offer, or Google MCPO.

</details>

## ​API Overview <a href="#api-overview" id="api-overview"></a>

### ​Which APIs Do You Need? <a href="#which-apis-do-you-need" id="which-apis-do-you-need"></a>

<details open>

<summary>Partners - Use Both APIs</summary>

**As a channel partner, you’ll use BOTH APIs:**

**Partner API (v2)** for:

* Registering new customer organizations
* Managing customer onboarding workflows
* Setting up cloud integrations (AWS CloudFormation, Azure auth)
* Tracking partner-specific metrics

**Public API (v1)** for:

* Accessing each customer’s commitment plans and metrics
* Retrieving cost optimization data for reporting
* Managing commitment plans on behalf of customers
* Building customer-facing dashboards

**Authentication:** Partner API key works for both APIs

</details>

<details open>

<summary>Direct Customers - Use Public API Only</summary>

**As a direct customer, you typically only need:**

**Public API (v1)** for:

* Accessing your organization’s commitment plans
* Retrieving cost and utilization metrics
* Integrating with internal tools and dashboards
* Automating cost optimization workflows

**Authentication:** Standard API key from your Archera account

</details>

## ​Ready to Get Started? <a href="#ready-to-get-started" id="ready-to-get-started"></a>

### ​Learn More About Archera <a href="#learn-more-about-archera" id="learn-more-about-archera"></a>

{% stepper %}
{% step %}

#### Understand Rate Optimization

Learn how rate optimization works and why it’s more effective than usage optimization

[What is Rate Optimization? →](/rate-optimization)
{% endstep %}

{% step %}

#### Discover Insured Commitments

See how Archera’s guaranteed commitments eliminate the risks of traditional cloud commitments

[Learn About Insured Commitments →](/insured-commitments)
{% endstep %}

{% step %}

#### Start Your Free Account

Connect your cloud billing data and begin optimizing within 24-48 hours

[Sign Up with Archera →](/getting-started/how-to-sign-up-with-archera)
{% endstep %}
{% endstepper %}

### ​API Integration Opportunities <a href="#api-integration-opportunities" id="api-integration-opportunities"></a>

Once you understand Archera’s value, here’s how you can integrate it programmatically into your workflows:

<details open>

<summary>Custom Cost Dashboards</summary>

**Build Internal Reporting Tools**

Use the Public API to create custom dashboards that show:

* Real-time cost optimization metrics
* Commitment utilization and performance
* Savings projections and ROI analysis
* Multi-cloud cost visibility in your BI tools

**API Endpoints:** `/commitment-plans`, `/metrics`, `/cost-analysis`

[Explore Public API →](https://docs.archera.ai/api-reference/public-api/public-api-reference)

</details>

<details open>

<summary>Automated Optimization Workflows</summary>

**Integrate Cost Optimization into CI/CD**

Automate commitment purchasing and optimization:

* Trigger commitment purchases based on usage patterns
* Set up automated alerts for optimization opportunities
* Integrate with infrastructure-as-code workflows
* Create approval workflows for large commitments

**API Endpoints:** `/commitment-plans/purchase`, `/automation-policies`, `/recommendations`

[View API Examples →](#quick-api-examples)

</details>

<details open>

<summary>Multi-Customer Management (Partners)</summary>

**Scale Cost Optimization Across Customers**

Use the Partner API to manage multiple customer organizations:

* Programmatically onboard new customers
* Deploy cloud integrations at scale
* Generate customer-specific optimization reports
* Track partner revenue and performance metrics

**API Endpoints:** `/organizations`, `/integrations`, `/partner-metrics`

[Partner API Documentation →](https://docs.archera.ai/api-reference/partner-api/partner-api)

</details>

<details open>

<summary>AWS Marketplace Integration</summary>

**Create CPPO Offers Programmatically**

Automate AWS Marketplace offer creation:

* Use AWS Catalog API to create CPPO offers
* Integrate with Archera’s resale authorization
* Track marketplace performance and revenue
* Manage offer lifecycle programmatically

**Implementation:** AWS Catalog API + Archera Partner API

[CPPO Guide →](https://docs.archera.ai/help-center/partner-guides/create-cppo-offers-for-archera-subscription)

</details>

<details open>

<summary>Cost Data Export &#x26; Analytics</summary>

**Extract Data for Advanced Analytics**

Pull Archera data into your data warehouse:

* Export commitment and utilization data
* Integrate with existing FinOps workflows
* Build predictive cost models
* Create custom allocation and chargeback systems

**API Endpoints:** `/export`, `/utilization-data`, `/cost-allocation`

[Data Export Examples →](#quick-api-examples)

</details>

### ​Quick API Examples <a href="#quick-api-examples" id="quick-api-examples"></a>

Get started with these common API integration patterns:

<details open>

<summary>Get Commitment Recommendations</summary>

**Retrieve AI-powered optimization recommendations**

```
curl -X GET "https://api.archera.ai/v1/recommendations" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

</details>

<details open>

<summary>Track Cost Savings</summary>

**Monitor your optimization performance**

```
curl -X GET "https://api.archera.ai/v1/metrics/savings?period=30d" \
  -H "x-api-key: YOUR_API_KEY"
```

</details>

<details open>

<summary>Create Customer Organization (Partners)</summary>

**Onboard a new customer via Partner API**

```
curl -X POST "https://api.archera.ai/v2/organizations" \
  -H "x-api-key: YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Company",
    "email": "admin@customer.com",
    "cloud_providers": ["aws", "azure"]
  }'
```

</details>

### ​ <a href="#explore-full-api-documentation" id="explore-full-api-documentation"></a>


# Rate Optimization

Understanding cloud rate optimization strategies and how to achieve significant cost savings without impacting your infrastructure

Rate optimization refers to selecting the most cost-effective pricing options for your cloud resources based on your workload requirements and usage patterns. By optimizing your rates, you can significantly reduce your cloud costs without compromising on performance or flexibility.

### ​What is Rate Optimization? <a href="#what-is-rate-optimization" id="what-is-rate-optimization"></a>

<div align="left"><figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/cost-reduction-matrix.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=0344f14269a2c64b5ad9d626d0d5704d" alt=""><figcaption></figcaption></figure></div>

While all of the above methods reduce costs, the highlighted section on the left focuses on **Rate Optimization** because they don’t impact your running infrastructure. Instead, you get a better price, or rate, for infrastructure you are already using.

### ​Why is Rate Optimization Important? <a href="#why-is-rate-optimization-important" id="why-is-rate-optimization-important"></a>

On-demand pricing in cloud services, while the most flexible, is the most expensive compared to other pricing options. Running your workloads solely on on-demand instances can lead to substantial costs, especially for long-running or persistent workloads.By implementing rate optimization strategies, you can potentially save **30% to 70%** on your cloud bills, depending on your specific use case, service usage, and workload characteristics.

### ​Understanding Your Current Costs <a href="#understanding-your-current-costs" id="understanding-your-current-costs"></a>

Before optimizing rates, you need visibility into your current spending patterns using native cloud cost management tools:

<table data-view="cards" data-full-width="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>AWS Cost Tools</strong></td><td><p><strong>Cost and Usage Reports (CUR)</strong></p><ul><li>Detailed cost data</li><li>Resource-level breakdown</li><li>Usage patterns</li></ul><p><strong>Cost Explorer</strong></p><ul><li>Cost visualization</li><li>Trend analysis</li><li>Right-sizing recommendations</li></ul></td></tr><tr><td><strong>Azure Cost Tools</strong></td><td><p><strong>Cost Management + Billing</strong></p><ul><li>Cost analysis</li><li>Budgets and alerts</li><li>Optimization insights</li></ul><p><strong>Azure Advisor</strong></p><ul><li>Cost recommendations</li><li>Reserved instance guidance</li><li>Resource optimization</li></ul></td></tr><tr><td><strong>GCP Cost Tools</strong></td><td><p><strong>Billing Export</strong></p><ul><li>Billing data export</li><li>BigQuery analysis</li><li>Custom reporting</li></ul><p><strong>Cost Management</strong></p><ul><li>Budget monitoring</li><li>Commitment analysis</li><li>Utilization insights</li></ul></td></tr></tbody></table>

{% hint style="info" %}
**Best Practice**: Connect your billing data to Archera’s free platform for superior cost analysis and optimization recommendations. Archera provides better insights than native cloud tools while automatically identifying optimization opportunities.
{% endhint %}

### ​What Rate Optimization is NOT <a href="#what-rate-optimization-is-not" id="what-rate-optimization-is-not"></a>

Returning to our four quadrants above - the unshaded areas on the right represent cost savings activities that do NOT fall under the umbrella of Rate Optimization. These are known as “usage optimization” - optimizing how you *consume* the cloud.

### ​Native Rate Optimization Options <a href="#native-rate-optimization-options" id="native-rate-optimization-options"></a>

Cloud providers offer several native pricing options that can help you optimize your costs:

#### ​1. Reserved Instances (RIs) <a href="#id-1-reserved-instances-ris" id="id-1-reserved-instances-ris"></a>

RIs allow you to commit to a specific instance configuration for a term of 1 or 3 years, in exchange for a significant discount compared to on-demand pricing. RIs are suitable for steady-state, predictable workloads.

#### ​2. Savings Plans <a href="#id-2-savings-plans" id="id-2-savings-plans"></a>

Savings Plans offer a flexible pricing model that provides discounts on your compute usage. By committing to a certain amount of compute usage (measured in dollars per hour) for a 1 or 3-year term, you can receive discounts on EC2, Fargate, and Lambda usage.

#### ​3. Spot Instances <a href="#id-3-spot-instances" id="id-3-spot-instances"></a>

Spot Instances allow you to bid on spare compute capacity at a discounted rate, often up to 90% lower than on-demand prices. Spot Instances are suitable for interruption-tolerant workloads, such as batch processing, testing, or stateless applications.

#### ​4. Enterprise Discount Programs (EDP/PPA) <a href="#id-4-enterprise-discount-programs-edp-ppa" id="id-4-enterprise-discount-programs-edp-ppa"></a>

Enterprise Discount Programs / Private Pricing Agreements are offered on an ad-hoc basis to individual organizations based on their historical consumption. While there are no publicly defined guidelines for when an organization may be offered an EDP/PPA, these generally provide high-level discounts off public prices in exchange for multi-year, often multi-million dollar spend commitments.

### ​Limitations of Native Options <a href="#limitations-of-native-options" id="limitations-of-native-options"></a>

While these native options offer significant cost savings, they also come with limitations and trade-offs:

* **Reserved Instances and Savings Plans** require long-term commitments, reducing flexibility
* **Spot Instances** can be interrupted with a 2-minute warning, which may not be suitable for all workloads
* **PPAs** require significant investment, often with implied growth obligations

### ​How Archera Integrates with Cost Management Tools <a href="#how-archera-integrates-with-cost-management-tools" id="how-archera-integrates-with-cost-management-tools"></a>

Archera works alongside your existing cost management tools to provide comprehensive optimization:

<details>

<summary>AWS Integration</summary>

**Cost and Usage Reports (CUR)**

* Archera analyzes your CUR data for optimization opportunities
* Identifies underutilized resources and commitment gaps
* Provides recommendations based on detailed usage patterns

**Cost Explorer Integration**

* Compare Archera recommendations with Cost Explorer forecasts
* Validate savings projections using historical cost data
* Monitor commitment performance alongside native AWS tools

</details>

<details>

<summary>Azure Integration</summary>

**Cost Management + Billing**

* Leverages Azure cost data for intelligent recommendations
* Analyzes spending trends and usage patterns
* Integrates with existing budget and alert configurations

**Ongoing Monitoring**

* Use Azure Cost Management to track Archera commitment performance
* Compare actual vs projected savings in native dashboards
* Maintain cost governance policies alongside optimization

</details>

<details>

<summary>Google Cloud Integration</summary>

**Billing Export Analysis**

* Processes GCP billing data for optimization insights
* Identifies CUD opportunities and usage patterns
* Provides BigQuery-compatible cost analysis

**Unified Reporting**

* Combine GCP native cost reporting with Archera insights
* Track optimization impact using familiar GCP tools
* Maintain existing cost monitoring workflows

</details>

### ​The Archera Advantage <a href="#the-archera-advantage" id="the-archera-advantage"></a>

Archera’s platform addresses native commitment limitations by providing:

<table data-view="cards" data-full-width="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Risk Mitigation</strong></td><td><p><strong>Investment Protection</strong></p><ul><li>Insurance against unused capacity</li><li>Guaranteed savings realization</li><li>Professional management included</li></ul></td></tr><tr><td><strong>Multi-Cloud Strategy</strong></td><td><p><strong>Unified Management</strong></p><ul><li>Single platform for all cloud commitments</li><li>Cross-cloud optimization strategies</li><li>Consolidated reporting and analytics</li></ul></td></tr><tr><td><strong>Transfer Flexibility</strong></td><td><p><strong>Account Mobility</strong></p><ul><li>Transfer commitments between accounts</li><li>Reorganize cloud structure without losing savings</li><li>Support for M&#x26;A activities</li></ul></td></tr></tbody></table>


# Insured Commitments

Learn about Archera’s Guaranteed Commitments that provide short-term insured cloud commitments with maximum flexibility and risk protection

Archera’s Guaranteed Commitments (GRIs & GSPs) offer a revolutionary approach to cloud cost optimization by providing short-term, insured commitments that eliminate the traditional risks associated with cloud reservations.

{% hint style="warning" %}
**When NOT to Use Archera**: The only scenario where native commitments may be preferred is when you have a stable, predictable workload that you’re confident will run unchanged for 3 years OR you can secure the maximum native discount with upfront payment. In all other cases, Archera’s guaranteed commitments provide additive value through flexibility and risk protection.
{% endhint %}

### ​What are Guaranteed Commitments? <a href="#what-are-guaranteed-commitments" id="what-are-guaranteed-commitments"></a>

Guaranteed Commitments are Archera’s solution to the inflexibility of traditional cloud commitments. They provide:

{% hint style="info" %}
**Guaranteed Reserved Instances (GRIs)**: Short-term reserved instances with insurance protection against underutilization\
\
**Guaranteed Savings Plans (GSPs)**: Flexible compute commitments with guaranteed utilization across multiple services
{% endhint %}

### ​Key Benefits <a href="#key-benefits" id="key-benefits"></a>

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><i class="fa-clock">:clock:</i> <strong>Shorter Terms</strong></td><td><p><strong>30-Day Minimum Terms</strong></p><ul><li>Start with 30-day commitments instead of 1-3 years</li><li>Maintain infrastructure flexibility</li><li>Perfect for dynamic workloads</li></ul></td></tr><tr><td><i class="fa-shield">:shield:</i> <strong>Insurance Protection</strong></td><td><p><strong>Commitment Loss Protection</strong></p><ul><li>Archera insures against underutilization</li><li>No risk of paying for unused capacity</li><li>Guaranteed savings realization</li></ul></td></tr><tr><td><i class="fa-gear">:gear:</i> <strong>Easy Management</strong></td><td><p><strong>Automated Optimization</strong></p><ul><li>Set automation policies for continuous optimization</li><li>Configurable savings thresholds</li><li>Weekly, monthly, or quarterly cadence</li></ul></td></tr><tr><td><i class="fa-money-bill">:money-bill:</i> <strong>No Hidden Fees</strong></td><td><p><strong>Transparent Pricing</strong></p><ul><li>What you see is what you get</li><li>No hidden fees deducted from savings</li><li>Clear, upfront pricing structure</li></ul></td></tr></tbody></table>

### ​How Guaranteed Commitments Work <a href="#how-guaranteed-commitments-work" id="how-guaranteed-commitments-work"></a>

#### Traditional Commitment Challenges

{% hint style="info" %}
Traditional cloud commitments present several challenges:

* **Long-term commitments** (1-3 years) reduce infrastructure flexibility
* **Utilization risk** - you pay for capacity whether you use it or not
* **Technology changes** can make commitments obsolete
* **Business changes** may alter infrastructure needs
  {% endhint %}

#### ​Archera’s Solution <a href="#archeras-solution" id="archeras-solution"></a>

{% hint style="success" %}
Guaranteed Commitments address these challenges through:

* **Insurance Layer**: Archera insures your commitments against underutilization
* **Flexible Terms**: Start with 30-day terms and scale as needed
* **Professional Management**: Expert optimization and ongoing management
* **Risk Transfer**: Archera takes on the utilization risk, not you
  {% endhint %}

### ​Commitment Types Available <a href="#commitment-types-available" id="commitment-types-available"></a>

<table data-card-size="large" data-view="cards" data-full-width="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Guaranteed Reserved Instances (GRIs)</strong></td><td><p><strong>Instance-Specific Commitments</strong></p><ul><li><strong>AWS</strong>: Individual EC2 instances, RDS, ElastiCache, DynamoDB</li><li><strong>Azure</strong>: Virtual Machine Reserved Instances, SQL Database, Cosmos DB</li><li><strong>Google Cloud</strong>: Compute Engine instances, Cloud SQL</li><li><strong>Term Options</strong>: 30-day minimum, up to 3 years</li><li><strong>Coverage</strong>: Specific instance types and sizes</li><li><strong>Best For</strong>: Predictable, instance-specific workloads</li></ul></td></tr><tr><td><strong>Guaranteed Savings Plans (GSPs)</strong></td><td><p><strong>Flexible Compute Commitments</strong></p><ul><li><strong>AWS</strong>: Broad compute services (EC2, Lambda, Fargate, ECS/EKS)</li><li><strong>Azure</strong>: Compute services across VM families and App Service plans</li><li><strong>Google Cloud</strong>: Spend-based and resource-based Committed Use Discounts</li><li><strong>Term Options</strong>: 30-day minimum, flexible duration</li><li><strong>Coverage</strong>: Dollar-per-hour commitment across compute services</li><li><strong>Best For</strong>: Dynamic workloads with varying compute needs</li></ul></td></tr></tbody></table>

### ​Commitment Comparison Matrix <a href="#commitment-comparison-matrix" id="commitment-comparison-matrix"></a>

When evaluating commitment options, use this comparison to understand the trade-offs:

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/commitment-comparison-matrix.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=5b49cd26421ed041206ce2a88d5e1865" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Key Considerations When Choosing:**

1. **How much will this commitment save me?** (Archera shows net savings with no hidden fees)
2. **What’s the discount rate for this commitment option?**
3. **How long until I break even and will my infrastructure be up at least that long?**
   {% endhint %}

### ​Important Metrics <a href="#important-metrics" id="important-metrics"></a>

When evaluating commitment performance using both Archera and native cloud tools, focus on these key metrics:

<details open>

<summary>Coverage Amount</summary>

**Definition**: What percentage of your reservable infrastructure has a commitment applied

**Target**: Generally, higher coverage is better as it maximizes cost savings across your infrastructure

**Measurement**: (Reserved Capacity / Total Reservable Capacity) × 100

**Native Tool Tracking**:

* AWS: Cost Explorer and Cost and Usage Reports
* Azure: Cost Management
* GCP: Billing reports

</details>

<details open>

<summary>Net Savings Rate</summary>

**Definition**: The aggregate impact of all your commitments relative to the on-demand rate

**Target**: Higher savings rates indicate more effective commitment strategies

**Measurement**: Total discount percentage achieved across all commitments

**Native Tool Tracking**:

* AWS: Cost Explorer and Cost and Usage Reports
* Azure: Cost Management
* GCP: Billing reports

</details>

<details open>

<summary>Utilization</summary>

**Definition**: How much of your purchased commitments you’re actually using

**Target**: As close to 100% as possible for maximum ROI

**Measurement**: (Used Commitment Hours / Purchased Commitment Hours) × 100

**Native Tool Tracking**:

* AWS: Cost Explorer and Cost and Usage Reports
* Azure: Cost Management
* GCP: Billing reports

</details>

### ​Commitment Planning Options <a href="#commitment-planning-options" id="commitment-planning-options"></a>

Archera provides three default commitment strategies:

<details open>

<summary>Recommended Plan - Start Here</summary>

**Focus**: 30-day GRIs and compute instances

**Philosophy**: Maximum flexibility with immediate savings

**Best For**: Organizations prioritizing flexibility over maximum savings

{% hint style="success" %}
Perfect for getting started with guaranteed commitments
{% endhint %}

</details>

<details open>

<summary>Balanced Plan - Most Popular</summary>

**Focus**: All reservable services with mixed terms

**Philosophy**: Balance of savings and flexibility

**Features**: Combines 30-day and 1-year commitments across all services

{% hint style="info" %}
Most customers choose this option for ongoing optimization
{% endhint %}

</details>

<details open>

<summary>High Savings Plan - Maximum Discount</summary>

**Focus**: Maximum discount through longer terms

**Features**: Includes 3-year commitments and upfront payments

**Consideration**: Higher savings but reduced flexibility

{% hint style="warning" %}
Only consider if you have highly predictable, long-term workloads
{% endhint %}

</details>

### ​Automation Policies <a href="#automation-policies" id="automation-policies"></a>

{% hint style="info" %}
Archera offers fully optional automation policies that:

* **Monitor** your infrastructure continuously
* **Apply** new commitments when savings thresholds are met
* **Operate** on your preferred cadence (weekly, monthly, quarterly)
* **Cancel** anytime with full control retained
  {% endhint %}

#### ​Policy Configuration <a href="#policy-configuration" id="policy-configuration"></a>

#### &#x20;<a href="#policy-configuration" id="policy-configuration"></a>

{% stepper %}
{% step %}
**Set Savings Threshold**

Define minimum savings amount required to trigger automation

{% hint style="success" %}
Start with a conservative threshold like $100/month to test automation
{% endhint %}
{% endstep %}

{% step %}
**Choose Cadence**

Select how frequently the system should evaluate new opportunities

{% hint style="info" %}
Weekly cadence works well for dynamic environments
{% endhint %}
{% endstep %}

{% step %}
**Monitor Performance**

Track automated savings and adjust thresholds as needed
{% endstep %}

{% step %}
**Maintain Control**

Cancel or modify policies anytime through the platform

{% hint style="info" %}
You always retain full control - automation is completely optional
{% endhint %}
{% endstep %}
{% endstepper %}

### ​Getting Started <a href="#getting-started" id="getting-started"></a>

Ready to implement Guaranteed Commitments? Here’s how to begin:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-user-plus">:user-plus:</i> <strong>Sign Up with Archera</strong></td><td>Create your account and connect your cloud environments.</td><td><a href="https://app.archera.ai/signup">https://app.archera.ai/signup</a></td></tr><tr><td><i class="fa-chart-line-up">:chart-line-up:</i> <strong>Platform Access</strong></td><td>Access the Archera platform to start managing commitments</td><td><a href="https://app.archera.ai">https://app.archera.ai</a></td></tr></tbody></table>

{% hint style="info" %}
**Risk-Free Optimization**: Guaranteed Commitments are completely opt-in and designed to eliminate traditional commitment risks. You maintain full control of your AWS account and infrastructure while benefiting from professional optimization and insurance protection.
{% endhint %}

### ​Why Choose Guaranteed Commitments? <a href="#why-choose-guaranteed-commitments" id="why-choose-guaranteed-commitments"></a>

{% hint style="success" %}
Traditional commitments require you to predict your infrastructure needs months or years in advance. Guaranteed Commitments let you optimize costs today while maintaining the flexibility to adapt tomorrow.
{% endhint %}

### ​Benefits Summary <a href="#benefits-summary" id="benefits-summary"></a>

### &#x20;<a href="#benefits-summary" id="benefits-summary"></a>

<table data-view="cards" data-full-width="false"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Immediate Savings</strong></td><td>Start saving immediately with 30-day terms</td></tr><tr><td><strong>Zero Risk</strong></td><td>Zero utilization risk through insurance protection</td></tr><tr><td><strong>Expert Management</strong></td><td>Professional management and optimization</td></tr><tr><td><strong>Transparent Pricing</strong></td><td>Transparent pricing with no hidden fees</td></tr><tr><td><strong>Automation</strong></td><td>Automated policies for hands-off optimization</td></tr><tr><td><strong>Full Control</strong></td><td>Full control and cancellation rights</td></tr></tbody></table>

{% hint style="warning" %}
**Remember**: The only time to consider native 3-year commitments over Archera is when you have completely predictable workloads that will run unchanged for 3 years AND you can get maximum upfront discounts. In all other scenarios, Archera’s guaranteed commitments provide superior value.
{% endhint %}


# How to Sign Up with Archera

Get started with Archera’s platform to begin optimizing your cloud costs through intelligent commitment management

Getting started with Archera is straightforward and designed to have you optimizing costs within minutes. Follow this guide to set up your account and begin your cloud cost optimization journey.

### ​Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before getting started, ensure you have:

<table data-card-size="large" data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><p><strong>Cloud Account Access</strong></p><p><strong>Account Permissions</strong></p><ul><li>Cloud account with billing access (AWS, Azure, or GCP)</li><li>Ability to create necessary integrations</li><li>Cost and usage data access</li></ul></td></tr><tr><td><p><strong>Cost Visibility Setup</strong></p><p><strong>Cost Management Tools</strong></p><ul><li>AWS: Cost and Usage Reports (CUR) configured</li><li>Azure: Cost Management + Billing enabled</li><li>GCP: Billing export configured</li><li>Basic understanding of your spending patterns</li></ul></td></tr><tr><td><p><strong>Basic Understanding</strong></p><p><strong>Cloud Knowledge</strong></p><ul><li>Familiarity with your cloud services</li><li>Understanding of your workload patterns</li><li>Desire to optimize cloud costs</li></ul></td></tr><tr><td><p><strong>Baseline Analysis</strong></p><p><strong>Current State Knowledge</strong></p><ul><li>Knowledge of top spending services</li><li>Understanding of usage patterns</li><li>Existing cost monitoring practices</li></ul></td></tr></tbody></table>

{% hint style="info" %}
**Recommended**: Set up native cost management tools (AWS Cost Explorer, Azure Cost Management, GCP Billing) before connecting to Archera. This provides baseline understanding and enables better optimization decisions.
{% endhint %}

### ​Step 1: Create Your Archera Account <a href="#step-1-create-your-archera-account" id="step-1-create-your-archera-account"></a>

{% stepper %}
{% step %}
**Navigate to Archera**

Go to [app.archera.ai](https://app.archera.ai/) and click “Sign Up” to create your account

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/signup-archera.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=b0603dcb3fdb4ce79183af18e0c9ec97" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Provide Account Details**

Enter your email, create a password, and provide basic organization information
{% endstep %}

{% step %}
**Verify Your Email**

Check your inbox for a verification email and click the confirmation link
{% endstep %}

{% step %}
**Complete Profile Setup**

Add your name, role, and organization details to complete your profile
{% endstep %}
{% endstepper %}

### ​Step 2: Connect Your Cloud Provider <a href="#step-2-connect-your-cloud-provider" id="step-2-connect-your-cloud-provider"></a>

Once your account is created, you’ll need to connect your cloud environment. Archera supports AWS, Azure, and Google Cloud Platform.

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/choose-provider-step.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=8a8d30ea9d2428d9647103374166622c" alt=""><figcaption></figcaption></figure>

#### ​Cloud Provider Integration <a href="#cloud-provider-integration" id="cloud-provider-integration"></a>

Archera uses secure, native integration methods for each cloud provider:

<details open>

<summary>AWS Integration</summary>

**CloudFormation Deployment:**

1. **Launch CloudFormation Stack**: Pre-configured template for secure integration
2. **IAM Role Creation**: Read-only role for cost analysis
3. **Minimal Permissions**: Only cost optimization permissions
4. **No Infrastructure Access**: Never accesses running workloads

   ![CloudFormation Screenshot](https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/cloudformation-screenshot.png?fit=max\&auto=format\&n=cCBfcsubiIlPNh4r\&q=85\&s=835ec26f9ca18d75cd3bc8780d1179df)

</details>

<details open>

<summary>Azure Integration</summary>

**Service Principal Setup:**

1. **App Registration**: Create service principal in Azure AD
2. **Reader Permissions**: Billing and cost management access
3. **Secure Connection**: OAuth-based authentication
4. **Cost Data Only**: No access to operational resources

</details>

<details open>

<summary>Google Cloud Integration</summary>

**Service Account Configuration:**

1. **Service Account**: Create dedicated service account
2. **Billing Permissions**: Cloud billing and asset inventory access
3. **JSON Key**: Secure key-based authentication
4. **Read-Only Access**: No modification permissions

</details>

<details open>

<summary>What Archera Accesses</summary>

**Required Data Access:**

* **Cost and Usage Data**: To analyze spending patterns
* **Resource Information**: To recommend appropriate commitments
* **Billing Information**: To calculate potential savings

**What Archera NEVER Accesses:**

* Your application data or workloads
* Running instances or services
* Security configurations
* Any operational infrastructure

</details>

#### ​Connection Process <a href="#connection-process" id="connection-process"></a>

{% stepper %}
{% step %}
**Select Cloud Provider**

Choose your cloud provider (AWS, Azure, or Google Cloud) from the integration options
{% endstep %}

{% step %}
**Follow Provider Instructions**

Each provider has specific integration steps guided by the platform
{% endstep %}

{% step %}
**Review Permissions**

Review the access permissions that will be granted
{% endstep %}

{% step %}
**Complete Integration**

Confirm the connection and verify successful integration
{% endstep %}
{% endstepper %}

### ​Step 3: Initial Cost Analysis <a href="#step-3-initial-cost-analysis" id="step-3-initial-cost-analysis"></a>

After connecting your cloud account, Archera will begin analyzing your usage:

{% hint style="info" %}
**Onboarding Process**: Connection is completely free and purely to access your billing data so Archera can make accurate recommendations based on your actual usage numbers. After connecting, it takes **24-48 hours** to unlock the full platform as historical data is processed.
{% endhint %}

#### ​Data Processing Timeline <a href="#data-processing-timeline" id="data-processing-timeline"></a>

#### &#x20;<a href="#data-processing-timeline" id="data-processing-timeline"></a>

<table data-card-size="large" data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><p><strong>Initial Connection</strong></p><p><strong>5-10 Minutes</strong></p><ul><li>Account connection verification</li><li>Basic cost data import</li><li>Infrastructure discovery</li></ul></td></tr><tr><td><p><strong>Full Platform Access</strong></p><p><strong>24-48 Hours</strong></p><ul><li>Historical usage analysis</li><li>Savings opportunity identification</li><li>Complete platform functionality unlocked</li></ul></td></tr></tbody></table>

#### ​What You’ll See First <a href="#what-youll-see-first" id="what-youll-see-first"></a>

Once initial processing completes, you’ll have access to:

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/immediate-savings-analysis.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=8690757d60cf9321a5502bdd7094c0be" alt=""><figcaption></figcaption></figure>

1. **Immediate Savings Analysis**: Quick wins for covering on-demand usage with short-term commitments
2. **Commitment Planner**: Three default strategies (Recommended, Balanced, High Savings)
3. **Cost Dashboard**: Overview of your current spending and optimization opportunities

### ​Step 4: Explore Your Savings Opportunities <a href="#step-4-explore-your-savings-opportunities" id="step-4-explore-your-savings-opportunities"></a>

#### ​Immediate Savings Analysis <a href="#immediate-savings-analysis" id="immediate-savings-analysis"></a>

Your first view will show immediate opportunities to cover on-demand usage with 30-day commitments:

* **Stop the Bleeding**: Identify on-demand resources that should have commitments
* **Quick Implementation**: Apply 30-day commitments for immediate savings
* **Risk-Free Start**: Begin optimization without long-term commitments

#### ​Commitment Planner <a href="#commitment-planner" id="commitment-planner"></a>

Explore three pre-configured commitment strategies:

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/default-commitment-plans.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=7994b668ed1c319788cb26aca1a5b558" alt=""><figcaption></figcaption></figure>

<details open>

<summary>Recommended Plan</summary>

**Focus**: Maximum flexibility with immediate savings

* Primarily 30-day guaranteed commitments
* Lowest risk, moderate savings
* Perfect for getting started

</details>

<details open>

<summary>Balanced Plan</summary>

**Focus**: Optimal balance of savings and flexibility

* All reservable services included
* Mix of 30-day and 1-year commitments
* Most popular choice for ongoing optimization

</details>

<details open>

<summary>High Savings Plan</summary>

**Focus**: Maximum cost reduction

* 3-year commitments with upfront payments
* Highest savings potential
* Reduced flexibility, maximum discounts

</details>

### ​Step 5: Implement Your First Plan <a href="#step-5-implement-your-first-plan" id="step-5-implement-your-first-plan"></a>

#### ​Applying a Commitment Plan <a href="#applying-a-commitment-plan" id="applying-a-commitment-plan"></a>

#### &#x20;<a href="#applying-a-commitment-plan" id="applying-a-commitment-plan"></a>

{% stepper %}
{% step %}
**Select Your Strategy**

Choose from Recommended, Balanced, or High Savings plans
{% endstep %}

{% step %}
**Review Details**

Click “View Details” to see specific commitments and covered infrastructure
{% endstep %}

{% step %}
**Customize if Needed**

Edit individual line items or create custom plans as desired
{% endstep %}

{% step %}
**Apply Plan**

Click “Apply Plan” to implement your chosen strategy and start saving
{% endstep %}
{% endstepper %}

#### ​Setting Up Automation (Optional) <a href="#setting-up-automation-optional" id="setting-up-automation-optional"></a>

Enable automation policies for hands-off optimization:

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/automation-toggle.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=1620a83cff379bcac1911600701e381a" alt=""><figcaption></figcaption></figure>

1. **Configure Thresholds**: Set minimum savings amounts to trigger automation
2. **Choose Cadence**: Select weekly, monthly, or quarterly evaluation
3. **Monitor Performance**: Track automated savings and adjust as needed
4. **Maintain Control**: Cancel or modify policies anytime

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/automation-modal.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=881cbcc527dd0e8705f6b40e0fdd4bf5" alt=""><figcaption></figcaption></figure>

### ​Step 6: Ongoing Management <a href="#step-6-ongoing-management" id="step-6-ongoing-management"></a>

#### ​Platform Features <a href="#platform-features" id="platform-features"></a>

Once you’re up and running, take advantage of:

<table data-card-size="large" data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><p><strong>Custom Plan Creation</strong></p><p><strong>Build Your Own Strategy</strong></p><ul><li>Create plans tailored to your needs</li><li>Mix commitment types and terms</li><li>Save and share plans with your team</li></ul></td></tr><tr><td><p><strong>Performance Monitoring</strong></p><p><strong>Track Your Success</strong></p><ul><li>Monitor utilization and savings</li><li>View breakeven timelines</li><li>Analyze coverage across services</li></ul></td></tr><tr><td><p><strong>Team Collaboration</strong></p><p><strong>Multi-User Support</strong></p><ul><li>Invite team members</li><li>Set permissions and roles</li><li>Share plans and reports</li></ul></td></tr><tr><td><p><strong>API Integration</strong></p><p><strong>Programmatic Access</strong></p><ul><li>REST API for custom integrations</li><li>Export data for reporting</li><li>Automate workflows</li></ul></td></tr></tbody></table>

#### ​Best Practices <a href="#best-practices" id="best-practices"></a>

1. **Start Small**: Begin with 30-day commitments to understand the platform
2. **Monitor Regularly**: Review savings and utilization weekly
3. **Use Automation**: Enable policies once comfortable with manual optimization
4. **Plan Ahead**: Consider business changes when selecting commitment terms

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/onboarding-end.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=a071953270bf4c36395d5c22ff11cd32" alt=""><figcaption></figcaption></figure>

### ​Security and Compliance <a href="#security-and-compliance" id="security-and-compliance"></a>

Archera maintains enterprise-grade security:

* **SOC 2 Type II Compliance**: Audited security controls and processes
* **Least Privilege Access**: Minimal required permissions for cost optimization
* **No Data Storage**: Cost data processed in real-time, not stored
* **Encryption**: All data transmitted using industry-standard encryption

{% hint style="info" %}
**Free Platform**: Archera’s platform is completely free to use. Connection is purely to access billing data for accurate recommendations. There are no hidden fees, and you keep 100% of your optimized savings. Full platform access is available 24-48 hours after connecting your cloud account.
{% endhint %}


# Supported Reservable Services

Comprehensive list of all cloud services supported by Archera’s platform across AWS, Azure, and Google Cloud

Archera’s platform supports **all reservable services** across major cloud providers. Customers can purchase and manage commitments for any service that supports reservations.

{% hint style="info" %}
**AWS SQL Server exception**: We do not currently cover AWS SQL Server because native savings rates are already low.
{% endhint %}

### ​AWS Reservable Services <a href="#aws-reservable-services" id="aws-reservable-services"></a>

Archera supports all AWS services that offer reservations or commitments, including:

* **Compute**: EC2 Reserved Instances (all types), Savings Plans, Lambda
* **Database**: RDS, ElastiCache, DynamoDB Reserved Capacity
* **Analytics**: Redshift, OpenSearch Reserved Instances
* **Storage**: EBS, S3 storage classes

{% embed url="<https://docs.aws.amazon.com/whitepapers/latest/cost-optimization-reservation-models/reservation-models-for-other-aws-services.html>" %}

### ​Azure Reservable Services <a href="#azure-reservable-services" id="azure-reservable-services"></a>

Archera supports all Azure services that offer reservations, including:

* **Compute**: Virtual Machine Reserved Instances (all VM series including D, E, F, G, H, L, M, N series), Azure Dedicated Host, App Service plans, Azure Container Instances
* **Database**: SQL Database (vCore and DTU models), Azure Database for MySQL, Azure Database for PostgreSQL, Azure Database for MariaDB, Cosmos DB (all APIs), Azure Cache for Redis (all tiers)
* **Storage**: Blob storage (all access tiers), Azure Files, Managed Disks (Premium SSD, Standard SSD, Standard HDD), Azure NetApp Files
* **Analytics**: Synapse Analytics (SQL pools, Spark pools), Data Factory (pipeline runs, data flows), Azure Databricks (all SKUs), HDInsight clusters
* **AI/ML**: Azure Cognitive Services, Azure Machine Learning compute instances
* **Networking**: VPN Gateway, ExpressRoute circuits, Azure Firewall
* **Other Services**: Azure VMware Solution, Azure Red Hat OpenShift, Azure Spring Cloud

{% embed url="<https://learn.microsoft.com/en-us/azure/cost-management-billing/reservations/save-compute-costs-reservations>" %}

### ​Google Cloud Reservable Services <a href="#google-cloud-reservable-services" id="google-cloud-reservable-services"></a>

Archera supports all Google Cloud services that offer Committed Use Discounts (CUDs), including:

* **Compute**: Compute Engine (all machine types), resource and spend-based CUDs
* **Database**: Cloud SQL (all database engines and configurations)
* **Analytics**: BigQuery slots, Cloud Storage, Dataflow
* **AI/ML**: Vertex AI, Cloud TPU

{% embed url="<https://cloud.google.com/docs/cuds>" %}

### ​Archera Advantages <a href="#archera-advantages" id="archera-advantages"></a>

When customers purchase commitments through Archera’s platform (via CPPO offers), they receive:

<table data-card-size="large" data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><p><strong>Transfer Flexibility</strong></p><p><strong>Account Mobility</strong></p><ul><li>Transfer commitments between accounts</li><li>Reorganize cloud structure without losing savings</li><li>Support for M&#x26;A activities</li></ul></td></tr><tr><td><p><strong>Risk Mitigation</strong></p><p><strong>Investment Protection</strong></p><ul><li>Insurance against unused capacity</li><li>Guaranteed savings realization</li><li>Professional management included</li></ul></td></tr><tr><td><p><strong>Multi-Cloud Strategy</strong></p><p><strong>Unified Management</strong></p><ul><li>Single platform for all cloud commitments</li><li>Cross-cloud optimization strategies</li><li>Consolidated reporting and analytics</li></ul></td></tr></tbody></table>

### ​Service Coverage Updates <a href="#service-coverage-updates" id="service-coverage-updates"></a>

#### ​Continuous Expansion <a href="#continuous-expansion" id="continuous-expansion"></a>

Archera’s platform automatically supports new reservable services as cloud providers introduce them:

* **AWS**: New instance types, services, and reservation options are added automatically
* **Azure**: New VM series, database options, and capacity types are supported upon release
* **Google Cloud**: New machine types, services, and commitment options are included immediately

#### ​Notification System <a href="#notification-system" id="notification-system"></a>

Partners and customers are notified when:

* New reservable services become available
* Existing services add new reservation options
* Pricing or terms for reservations change
* Optimization opportunities arise from new service options

{% hint style="info" %}
**For CPPO Partners**: This comprehensive service coverage means your customers can optimize costs for their entire cloud infrastructure through a single Archera subscription, maximizing the value of your marketplace offers.
{% endhint %}

### ​Next Steps <a href="#next-steps" id="next-steps"></a>

### ​Cloud Provider Reservation References <a href="#cloud-provider-reservation-references" id="cloud-provider-reservation-references"></a>

For detailed information about reservable services across cloud providers, consult these comprehensive documentation resources:

#### ​AWS Reserved Instances & Savings Plans <a href="#aws-reserved-instances-and-savings-plans" id="aws-reserved-instances-and-savings-plans"></a>

{% embed url="<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-reserved-instances.html>" %}

{% embed url="<https://docs.aws.amazon.com/savingsplans/latest/userguide/>" %}

{% embed url="<https://aws.amazon.com/aws-cost-management/aws-cost-optimization/reserved-instances/>" %}

{% embed url="<https://docs.aws.amazon.com/whitepapers/latest/cost-optimization-reservation-models/reservation-models-for-other-aws-services.html>" %}

#### ​Google Cloud Committed Use Discounts <a href="#google-cloud-committed-use-discounts" id="google-cloud-committed-use-discounts"></a>

{% embed url="<https://cloud.google.com/docs/cuds>" %}

{% embed url="<https://cloud.google.com/compute/docs/instances/committed-use-discounts-overview>" %}

#### ​Azure Reservations <a href="#azure-reservations" id="azure-reservations"></a>

{% embed url="<https://learn.microsoft.com/en-us/azure/cost-management-billing/reservations/save-compute-costs-reservations>" %}

{% embed url="<https://azure.microsoft.com/en-us/pricing/reserved-capacity>" %}

{% hint style="info" %}
**For Partners**: Understanding these reservation types helps you better assist customers in selecting appropriate CPPO offers. Archera’s platform supports purchasing and managing all these commitment types.
{% endhint %}


# API & MCP Reference

Connect to Archera through MCP or the public API

Choose how you want to connect to Archera:

## MCP documentation

Connect AI assistants and developer tools to your Archera account.

[Open the MCP documentation →](https://docs.archera.ai/api-reference/mcp-server/mcp)

## API documentation

Access Archera programmatically with an API key.

[Open the API documentation →](https://docs.archera.ai/api-reference/public-api/api-key-access)

If you have questions or need support, please contact our team at <support@archera.ai>.


# MCP Server

The Archera MCP Server connects your AI assistant to your Archera account using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), giving it direct access to your cloud commitments, cost data, and optimization recommendations. Archera hosts and manages the remote MCP server with OAuth authentication.

**MCP server URL:** `https://mcp.archera.ai/mcp`

***

## Authentication

The Archera MCP Server uses OAuth Authorization Code with PKCE. MCP clients that support Dynamic Client Registration can register themselves automatically during setup.

Most clients start a browser-based Archera login when you connect to or start the MCP server. Claude Code is different: add the server first, then run `/mcp` inside Claude Code to authenticate.

If your MCP client asks you to manually provide a `client_id`, update the client or contact Archera support.

***

## Set up your client

Select your client below for setup instructions. All clients should connect to `https://mcp.archera.ai/mcp` and authenticate with your existing Archera login.

<details>

<summary>Claude Code</summary>

Run the following command in your terminal:

```bash
claude mcp add --transport http --scope user archera https://mcp.archera.ai/mcp
```

Then open Claude Code and run:

```
/mcp
```

Select the `archera` server and follow the browser login flow. Once you approve access, the server is available in future Claude Code sessions. The `--scope user` flag makes the server available across projects; drop it if you want the server configured only for the current project.

</details>

<details>

<summary>OpenAI Codex</summary>

Run the following command in your terminal:

```bash
codex mcp add archera --url https://mcp.archera.ai/mcp
```

Verify the server is configured:

```bash
codex mcp list
```

Codex shares MCP configuration between the CLI and IDE extension. Start Codex after adding the server and complete the OAuth login flow when prompted.

</details>

<details>

<summary>Claude Desktop</summary>

Open Claude Desktop, then go to **Settings** -> **Connectors**.

1. Click **Add connector** or **+** -> **Add custom connector**.
2. If prompted for a connector type, choose **Custom** -> **Web**.
3. Name the connector `Archera`.
4. Enter the connector URL: `https://mcp.archera.ai/mcp`
5. Click **Add**, then click **Connect** to authenticate with Archera.

Claude Desktop uses the same remote connector flow as Claude on the web. The local Developer config editor is intended for local MCP server processes.

</details>

<details>

<summary>Claude.ai</summary>

1. Go to **Settings** -> **Connectors**.
2. Click **Add connector** or **+** -> **Add custom connector**.
3. If prompted for a connector type, choose **Custom** -> **Web**.
4. Name the connector `Archera`.
5. Enter the connector URL: `https://mcp.archera.ai/mcp`
6. Click **Add**, then click **Connect** to authenticate with Archera.

For Team or Enterprise plans, an owner may need to add the connector from **Organization settings** -> **Connectors** before members can connect it.

</details>

<details>

<summary>Cursor</summary>

Go to **Cursor** -> **Settings** -> **Cursor Settings** -> **MCP** and add the server. You can also edit your `mcp.json` directly:

```json
{
  "mcpServers": {
    "archera": {
      "type": "http",
      "url": "https://mcp.archera.ai/mcp"
    }
  }
}
```

Use `~/.cursor/mcp.json` for a global server or `.cursor/mcp.json` for a project-specific server. Start or refresh the server in Cursor, then follow the OAuth prompt to connect your Archera account.

</details>

<details>

<summary>Gemini CLI</summary>

Run the following command in your terminal:

```bash
gemini mcp add archera https://mcp.archera.ai/mcp --transport http --scope user
```

Start Gemini CLI. If authentication does not start automatically, run:

```
/mcp auth archera
```

The `--scope user` flag makes the server available across projects; use `--scope project` if you want the server configured only for the current project.

</details>

<details>

<summary>Cline</summary>

Open the Cline panel in VS Code, then open **MCP Servers** from the panel menu.

1. Select the **Remote Servers** tab.
2. Enter server name `archera`.
3. Enter server URL `https://mcp.archera.ai/mcp`.
4. Select **Streamable HTTP** as the transport type.
5. Click **Add Server**.
6. If Cline shows **Authentication required**, click **Authenticate** and complete the browser login flow.

For advanced setup, add the server to Cline's MCP config:

```json
{
  "mcpServers": {
    "archera": {
      "url": "https://mcp.archera.ai/mcp",
      "type": "streamableHttp",
      "disabled": false
    }
  }
}
```

</details>

<details>

<summary>Zed</summary>

Open the Agent Panel's settings view and click **Add Custom Server**, or add the server directly to your Zed settings:

```json
{
  "context_servers": {
    "archera": {
      "url": "https://mcp.archera.ai/mcp"
    }
  }
}
```

Zed prompts for OAuth authentication when the remote MCP server has no configured `Authorization` header.

</details>

<details>

<summary>VS Code (GitHub Copilot)</summary>

Open the Command Palette with `CMD+Shift+P`, select **MCP: Add Server**, choose **HTTP**, and enter:

```
https://mcp.archera.ai/mcp
```

Name the server `archera`, then choose whether to save it globally in your user profile or in the current workspace.

You can also open your user MCP configuration and add:

```json
{
  "servers": {
    "archera": {
      "type": "http",
      "url": "https://mcp.archera.ai/mcp"
    }
  }
}
```

Start the server, confirm that you trust it if prompted, and complete the OAuth login flow.

</details>

<details>

<summary>Windsurf</summary>

Open the Cascade panel, select the **MCPs** icon, or go to **Windsurf Settings** -> **Cascade** -> **MCP Servers**. Add a custom MCP server with this configuration:

```json
{
  "mcpServers": {
    "archera": {
      "serverUrl": "https://mcp.archera.ai/mcp"
    }
  }
}
```

If you edit the raw config directly, it is stored in `~/.codeium/windsurf/mcp_config.json`. Start or refresh the server, then follow the OAuth prompt to connect your Archera account.

</details>

<details>

<summary>Warp</summary>

Go to **Settings** -> **Agents** -> **MCP servers** -> **+ Add** and select **Streamable HTTP or SSE Server (URL)**. Enter the following:

```json
{
  "mcpServers": {
    "archera": {
      "url": "https://mcp.archera.ai/mcp"
    }
  }
}
```

Start the server. If you have not authenticated before, Warp opens a browser window to authenticate with Archera.

</details>

<details>

<summary>Amp</summary>

**VS Code Extension:** Add the server via the Amp VS Code extension settings, or update your `settings.json`:

```json
"amp.mcpServers": {
  "archera": {
    "url": "https://mcp.archera.ai/mcp"
  }
}
```

**Amp CLI:**

```bash
amp mcp add archera https://mcp.archera.ai/mcp
```

Amp starts the OAuth flow in your browser when the remote server starts. If the token becomes stale, run `amp mcp oauth logout archera` and restart Amp to authenticate again.

</details>

<details>

<summary>Other clients</summary>

The Archera MCP server works with clients that support Streamable HTTP, OAuth Authorization Code with PKCE, and Dynamic Client Registration. Use `https://mcp.archera.ai/mcp` as the server URL in your client's MCP configuration.

Discovery endpoints:

```
Protected resource metadata:
https://mcp.archera.ai/.well-known/oauth-protected-resource/mcp

Authorization server metadata:
https://api.archera.ai/.well-known/oauth-authorization-server

Dynamic client registration:
https://api.archera.ai/oauth/register
```

</details>

***

## Example prompts

Once connected, try these prompts to get started:

**Visibility**

* What commitment plans do I have active right now?
* Show me my Reserved Instance and Savings Plan coverage across all AWS accounts
* Which of my commitments are expiring in the next 60 days?
* What's my current on-demand spend versus committed spend?

**Analysis**

* Where am I most over- or under-committed?
* Show me EC2 utilization and coverage for the past 30 days
* Which accounts have the lowest commitment coverage?
* Are there any unused reservations I should be aware of?

**Optimization**

* What savings opportunities does Archera see for my environment?
* Generate a commitment plan recommendation for my production AWS account
* How much could I save by converting my top on-demand spend to Savings Plans?
* Compare my commitment efficiency this quarter versus last quarter

***

## Available tools

The Archera MCP server gives your AI assistant access to:

**Commitment management** View and manage your full portfolio of Reserved Instances, Savings Plans, and Archera Insured Commitments across all linked cloud accounts and services. Check status, term lengths, payment options, and renewal dates.

**Coverage & utilization** Analyze how well your existing commitments are being used. Identify underutilized reservations, coverage gaps by service or region, and accounts where on-demand spend is higher than it should be.

**Recommendations & planning** Generate commitment plans and savings recommendations based on your actual usage patterns. Model different scenarios, including term length, payment type, and coverage targets, to find the right balance of savings and flexibility for your organization.

**Spend & forecasting** Query historical cost data broken down by account, service, region, or commitment type. Get projected spend estimates based on current commitments and usage trends.

**Account management** View linked cloud accounts, their coverage summaries, and commitment activity across your Archera organization.

***

## Troubleshooting

**Auth not completing in Claude Code** Run `/mcp` inside Claude Code, select the `archera` server, and choose the authentication option. If the browser does not open automatically, copy the URL from the terminal and paste it manually. If your client uses a local callback server, make sure the callback port is not blocked by a firewall or VPN.

**Client asks for a client ID** Make sure your MCP client supports OAuth Dynamic Client Registration. If the client still requires a manually issued client ID, update the client or contact <support@archera.ai>.

**Reconnecting or switching accounts** In Claude Code, type `/mcp`, select the `archera` server, and choose **Clear authentication**. Then re-run the setup command to trigger a fresh login.

**Missing tools or data** Ensure your Archera account has the necessary permissions and that authentication completed successfully. Try disconnecting and reconnecting the MCP server.

**Connection issues** Verify the server URL is correct: `https://mcp.archera.ai/mcp`. Check that your network can reach `mcp.archera.ai` and `api.archera.ai`.

For further help, contact <support@archera.ai>.


# Public API Reference

The Archera Public API gives you programmatic access to your cloud cost optimization data. Retrieve real-time metrics like lifetime savings, coverage, and utilization across AWS, Azure, and GCP. Access AI-powered commitment recommendations and integrate your savings data into custom dashboards, reporting tools, and internal workflows.

Authenticate with an API key from your user settings and start building. Whether you're creating executive dashboards, automating alerts, or connecting Archera to your FinOps platform, the Public API provides secure, rate-limited access to all your organization's optimization insights.


# API Key Access

To use this API, you need an API key.

#### How to Create an API Key

1. Log in to the Archera.ai web application.
2. Navigate to **User Settings > API Access**. [Open Settings](https://app.archera.ai/settings?tab=api\&section=user)
3. Click **Create New API Key**.
4. Copy and securely store your new API key.

#### How to Use Your API Key

Use the `x-api-key` header:

```bash
curl -H 'x-api-key: YOUR_API_KEY' https://api.archera.ai/v1/org/{org_id}/metrics?provider=aws
```

Keep your API key secure. If you believe your key has been compromised, deactivate it in the web application and generate a new one.

#### How to find your Organization ID

1. Log in to the Archera.ai web application.
2. Navigate to **User Settings > Organization**.
3. Your Organization ID is displayed at the top of the page. You can also find it in the URL when visiting the Archera app `&orgId=<org_id>`


# Commitment Plans

API for managing commitment plans

## /commitment-plans/{plan\_id}

> Retrieves detailed information about a specific commitment plan, including costs, savings projections, and commitment coverage.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans","description":"API for managing commitment plans"}],"paths":{"/v1/org/{org_id}/commitment-plans/{plan_id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlan"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans"],"summary":"/commitment-plans/{plan_id}","description":"Retrieves detailed information about a specific commitment plan, including costs, savings projections, and commitment coverage."}}},"components":{"schemas":{"CommitmentPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"org_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"is_calculating":{"type":"boolean"},"status":{"enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"max_term":{"type":["string","null"]},"covered_ondemand_cost_hourly":{"type":"number"},"before_ondemand_cost_hourly":{"type":"number"},"before_reserved_cost_hourly":{"type":"number"},"amortized_cost_hourly":{"type":"number"},"recurring_cost_hourly":{"type":"number"},"upfront_cost_hourly":{"type":"number"},"before_cost_hourly":{"type":"number"},"after_cost_hourly":{"type":"number"},"total_cost_hourly":{"type":"number"},"savings_hourly":{"type":"number"},"fee_hourly":{"type":"number"},"commitment_coverage":{"type":"number"},"minimum_commitment_cost":{"type":"number"},"breakeven_hours":{"type":"number"},"total_savings":{"type":"number"},"monthly_savings":{"type":"number"},"total_monthly_before_cost":{"type":"number"}},"required":["after_cost_hourly","amortized_cost_hourly","before_cost_hourly","before_ondemand_cost_hourly","before_reserved_cost_hourly","breakeven_hours","commitment_coverage","covered_ondemand_cost_hourly","created_at","fee_hourly","id","is_calculating","max_term","minimum_commitment_cost","monthly_savings","name","org_id","recurring_cost_hourly","savings_hourly","status","total_cost_hourly","total_monthly_before_cost","total_savings","upfront_cost_hourly"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /commitment-plans/{plan\_id}/apply

> Executes a commitment purchase plan, initiating the commitment purchase process. This action will mark the plan as edited and record the user who initiated the purchase. The plan will then be processed for actual commitment purchases according to the plan specifications.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans","description":"API for managing commitment plans"}],"paths":{"/v1/org/{org_id}/commitment-plans/{plan_id}/apply":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlan"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans"],"summary":"/commitment-plans/{plan_id}/apply","description":"Executes a commitment purchase plan, initiating the commitment purchase process. This action will mark the plan as edited and record the user who initiated the purchase. The plan will then be processed for actual commitment purchases according to the plan specifications."}}},"components":{"schemas":{"CommitmentPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"org_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"is_calculating":{"type":"boolean"},"status":{"enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"max_term":{"type":["string","null"]},"covered_ondemand_cost_hourly":{"type":"number"},"before_ondemand_cost_hourly":{"type":"number"},"before_reserved_cost_hourly":{"type":"number"},"amortized_cost_hourly":{"type":"number"},"recurring_cost_hourly":{"type":"number"},"upfront_cost_hourly":{"type":"number"},"before_cost_hourly":{"type":"number"},"after_cost_hourly":{"type":"number"},"total_cost_hourly":{"type":"number"},"savings_hourly":{"type":"number"},"fee_hourly":{"type":"number"},"commitment_coverage":{"type":"number"},"minimum_commitment_cost":{"type":"number"},"breakeven_hours":{"type":"number"},"total_savings":{"type":"number"},"monthly_savings":{"type":"number"},"total_monthly_before_cost":{"type":"number"}},"required":["after_cost_hourly","amortized_cost_hourly","before_cost_hourly","before_ondemand_cost_hourly","before_reserved_cost_hourly","breakeven_hours","commitment_coverage","covered_ondemand_cost_hourly","created_at","fee_hourly","id","is_calculating","max_term","minimum_commitment_cost","monthly_savings","name","org_id","recurring_cost_hourly","savings_hourly","status","total_cost_hourly","total_monthly_before_cost","total_savings","upfront_cost_hourly"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /commitment-plans/default

> Retrieves the three default Archera commitment plans (High Savings, Balanced, Recommended) for the specified cloud provider. These plans are automatically generated based on the organization's usage patterns. Each plan offers different trade-offs between cost savings and flexibility.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans","description":"API for managing commitment plans"}],"paths":{"/v1/org/{org_id}/commitment-plans/default":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider to get default plans for","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommitmentPlan"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans"],"summary":"/commitment-plans/default","description":"Retrieves the three default Archera commitment plans (High Savings, Balanced, Recommended) for the specified cloud provider. These plans are automatically generated based on the organization's usage patterns. Each plan offers different trade-offs between cost savings and flexibility."}}},"components":{"schemas":{"CommitmentPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"org_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"is_calculating":{"type":"boolean"},"status":{"enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"max_term":{"type":["string","null"]},"covered_ondemand_cost_hourly":{"type":"number"},"before_ondemand_cost_hourly":{"type":"number"},"before_reserved_cost_hourly":{"type":"number"},"amortized_cost_hourly":{"type":"number"},"recurring_cost_hourly":{"type":"number"},"upfront_cost_hourly":{"type":"number"},"before_cost_hourly":{"type":"number"},"after_cost_hourly":{"type":"number"},"total_cost_hourly":{"type":"number"},"savings_hourly":{"type":"number"},"fee_hourly":{"type":"number"},"commitment_coverage":{"type":"number"},"minimum_commitment_cost":{"type":"number"},"breakeven_hours":{"type":"number"},"total_savings":{"type":"number"},"monthly_savings":{"type":"number"},"total_monthly_before_cost":{"type":"number"}},"required":["after_cost_hourly","amortized_cost_hourly","before_cost_hourly","before_ondemand_cost_hourly","before_reserved_cost_hourly","breakeven_hours","commitment_coverage","covered_ondemand_cost_hourly","created_at","fee_hourly","id","is_calculating","max_term","minimum_commitment_cost","monthly_savings","name","org_id","recurring_cost_hourly","savings_hourly","status","total_cost_hourly","total_monthly_before_cost","total_savings","upfront_cost_hourly"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /commitment-plans/recommended

> Retrieves only the recommended Archera commitment plan for the specified cloud provider. This is the optimal plan automatically selected based on the organization's usage patterns, balancing cost savings with flexibility. Returns a 204 No Content response if no recommended plan is available for the specified provider.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans","description":"API for managing commitment plans"}],"paths":{"/v1/org/{org_id}/commitment-plans/recommended":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider to get the recommended plan for","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlan"}}}},"204":{"description":"No Content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans"],"summary":"/commitment-plans/recommended","description":"Retrieves only the recommended Archera commitment plan for the specified cloud provider. This is the optimal plan automatically selected based on the organization's usage patterns, balancing cost savings with flexibility. Returns a 204 No Content response if no recommended plan is available for the specified provider."}}},"components":{"schemas":{"CommitmentPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"org_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"is_calculating":{"type":"boolean"},"status":{"enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"max_term":{"type":["string","null"]},"covered_ondemand_cost_hourly":{"type":"number"},"before_ondemand_cost_hourly":{"type":"number"},"before_reserved_cost_hourly":{"type":"number"},"amortized_cost_hourly":{"type":"number"},"recurring_cost_hourly":{"type":"number"},"upfront_cost_hourly":{"type":"number"},"before_cost_hourly":{"type":"number"},"after_cost_hourly":{"type":"number"},"total_cost_hourly":{"type":"number"},"savings_hourly":{"type":"number"},"fee_hourly":{"type":"number"},"commitment_coverage":{"type":"number"},"minimum_commitment_cost":{"type":"number"},"breakeven_hours":{"type":"number"},"total_savings":{"type":"number"},"monthly_savings":{"type":"number"},"total_monthly_before_cost":{"type":"number"}},"required":["after_cost_hourly","amortized_cost_hourly","before_cost_hourly","before_ondemand_cost_hourly","before_reserved_cost_hourly","breakeven_hours","commitment_coverage","covered_ondemand_cost_hourly","created_at","fee_hourly","id","is_calculating","max_term","minimum_commitment_cost","monthly_savings","name","org_id","recurring_cost_hourly","savings_hourly","status","total_cost_hourly","total_monthly_before_cost","total_savings","upfront_cost_hourly"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /commitment-plans/{plan\_id}/line-items

> Retrieves line items for a specific commitment plan, including offer details, costs, and savings information. Line items represent individual commitment purchases within the plan.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans","description":"API for managing commitment plans"}],"paths":{"/v1/org/{org_id}/commitment-plans/{plan_id}/line-items":{"get":{"parameters":[{"in":"query","name":"order_by","description":"Field to order results by","schema":{"type":["string","null"],"default":"id","enum":["id","plan_id","offer_id","account_id","amortized_cost","upfront_cost","recurring_cost","total_cost","savings","fee","covered_ondemand_cost","before_ondemand_cost","before_reserved_cost","covered_units","before_cost","monthly_savings","breakeven_hours","discount_rate","monthly_cost","selected_quantity",null,"offer.type","offer.duration_seconds"]},"required":false},{"in":"query","name":"desc","description":"Sort in descending order if true","schema":{"type":["boolean","null"],"default":null},"required":false},{"in":"query","name":"segment_id","description":"Filter line items by segment ID","schema":{"type":"string"},"required":false},{"in":"query","name":"resource_match_ids","description":"Filter line items by specific resource match IDs","schema":{"type":"array","items":{"type":"string","format":"uuid"}},"required":false,"explode":true,"style":"form"},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommitmentPlanLineItem_Exclude_CoveredServices"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans"],"summary":"/commitment-plans/{plan_id}/line-items","description":"Retrieves line items for a specific commitment plan, including offer details, costs, and savings information. Line items represent individual commitment purchases within the plan."}}},"components":{"schemas":{"CommitmentPlanLineItem_Exclude_CoveredServices":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"plan_id":{"type":"string","format":"uuid"},"offer_id":{"type":"string","format":"uuid"},"lease_menu_item_id":{"type":["string","null"],"format":"uuid"},"account_id":{"type":["string","null"]},"recommended_quantity":{"type":"integer","description":"Recommended number of units to purchase"},"selected_quantity":{"type":"integer","description":"Selected number of units to purchase"},"recommended_commitment":{"type":"number","description":"Recommended hourly commitment amount ($/hour for Savings Plans, 0 for instance RIs)"},"selected_commitment":{"type":"number","description":"Selected hourly commitment amount ($/hour for Savings Plans, 0 for instance RIs)"},"is_selected":{"type":"boolean","description":"Whether this line item is selected for purchase"},"after_amortized_cost":{"type":"number","description":"Hourly amortized cost of the commitment (upfront + recurring)"},"upfront_cost":{"type":"number","description":"Total upfront payment required (not hourly rate)"},"recurring_cost":{"type":"number","description":"Hourly recurring cost"},"before_cost":{"type":"number","description":"Total hourly cost before this commitment (ondemand + existing reservations)"},"before_ondemand_cost":{"type":"number","description":"Hourly ondemand cost before this commitment"},"before_reserved_cost":{"type":"number","description":"Hourly reserved cost from existing commitments"},"covered_ondemand_cost":{"type":"number","description":"Hourly ondemand cost that will be covered by this commitment"},"after_covered_units":{"type":"number","description":"Units that will be covered after the plan is applied"},"total_cost":{"type":"number","description":"Total cost of this commitment over its full term"},"monthly_cost":{"type":"number","description":"Monthly cost of this commitment"},"savings":{"type":"number","description":"Hourly savings compared to ondemand pricing"},"monthly_savings":{"type":"number","description":"Average monthly savings compared to ondemand pricing"},"total_savings":{"type":"number","description":"Total savings over the commitment term"},"fee":{"type":"number","description":"Estimated Archera premium (hourly) based on quoted maximum savings. See https://www.archera.ai/pricing for details."},"discount_rate":{"type":"number","description":"Discount percentage vs ondemand"},"breakeven_hours":{"type":"number","description":"Hours of usage needed until the achieved savings is greater than the remaining commitment for this line item"},"contract_term":{"description":"Commitment term (e.g., 'one_year_gris', 'thirty_day_gris')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment structure (No Upfront, Partial Upfront, All Upfront)","enum":["No Upfront","Partial Upfront","All Upfront"]},"contract_spec":{"description":"Detailed contract specifications including commitment type and properties","$ref":"#/components/schemas/PurchasePlanContractSpec"},"offer":{"description":"Detailed information about the commitment offer","$ref":"#/components/schemas/PublicCommitmentOffer"}},"required":["account_id","after_amortized_cost","after_covered_units","before_cost","before_ondemand_cost","before_reserved_cost","breakeven_hours","contract_spec","contract_term","covered_ondemand_cost","discount_rate","fee","id","is_selected","lease_menu_item_id","monthly_cost","monthly_savings","offer","offer_id","payment_option","plan_id","recommended_commitment","recommended_quantity","recurring_cost","savings","selected_commitment","selected_quantity","total_cost","total_savings","upfront_cost"],"additionalProperties":false},"PurchasePlanContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string"},"properties":{"type":"object","default":{},"additionalProperties":{}},"term":{"default":null,"type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"payment_option":{"default":null,"type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]}},"required":["commitment_type"],"additionalProperties":false},"PublicCommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["aws","azure","gcp"]},"provider_offering_id":{"type":"string"},"type":{"type":"string"},"display_name":{"type":["string","null"]},"leased_display_name":{"type":["string","null"]},"region":{"type":["string","null"]},"duration_seconds":{"type":"number"},"upfront_cost":{"type":"number"},"recurring_cost":{"type":"number"},"offering_class":{"enum":["standard","convertible",null]},"payment_option":{"enum":["No Upfront","Partial Upfront","All Upfront",null]},"offering_id":{"type":["string","null"]},"product_description":{"type":["string","null"]},"instance_family":{"type":["string","null"]},"instance_type":{"type":["string","null"]},"tenancy":{"type":["string","null"]},"az":{"type":["string","null"]},"is_multi_az":{"type":["boolean","null"]},"is_flexible":{"type":["boolean","null"]},"plan_type":{"type":["string","null"]}},"required":["az","display_name","duration_seconds","id","instance_family","instance_type","is_flexible","is_multi_az","leased_display_name","offering_id","plan_type","product_description","provider","provider_offering_id","recurring_cost","region","tenancy","type","upfront_cost"],"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /commitment-plans/{plan\_id}/resource-matches

> Retrieves resource matches for a specific commitment plan, showing how resources map to commitment purchases with cost and usage details.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans","description":"API for managing commitment plans"}],"paths":{"/v1/org/{org_id}/commitment-plans/{plan_id}/resource-matches":{"get":{"parameters":[{"in":"query","name":"order_by","description":"Field to order results by","schema":{"type":["string","null"],"default":"covered_ondemand_cost","enum":["id","unmatched_units","total_units","ondemand_price","reserved_cost","explanation_unmatched","coverage","ondemand_cost","covered_ondemand_cost","before_cost","after_cost","covered_units","average_savings","average_monthly_savings","monthly_after_cost",null]},"required":false},{"in":"query","name":"desc","description":"Sort in descending order if true","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"start_date","description":"Start date for resource usage data","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date for resource usage data","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"line_item_ids","description":"Filter by specific line item IDs","schema":{"type":"array","items":{"type":"string","format":"uuid"}},"required":false,"explode":true,"style":"form"},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommitmentPlanResourceMatch"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans"],"summary":"/commitment-plans/{plan_id}/resource-matches","description":"Retrieves resource matches for a specific commitment plan, showing how resources map to commitment purchases with cost and usage details."}}},"components":{"schemas":{"CommitmentPlanResourceMatch":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the resource match"},"total_units":{"type":"number","description":"Total resource usage units"},"before_uncovered_units":{"type":"number","description":"Units not covered at the moment (before this plan)"},"after_covered_units":{"type":"number","description":"Units that will be covered after the plan is applied"},"after_uncovered_units":{"type":"number","description":"Units that will remain uncovered after the plan to avoid overcommit"},"ondemand_price":{"type":"number","description":"Ondemand cost per unit-hour"},"if_all_ondemand_cost":{"type":"number","description":"Hourly cost if paying all the units with ondemand price"},"before_ondemand_cost":{"type":"number","description":"Current hourly ondemand cost for units not covered by existing commitments"},"after_ondemand_cost":{"type":"number","description":"Hourly ondemand cost remaining after applying this plan"},"covered_ondemand_cost":{"type":"number","description":"Hourly ondemand cost for units that will be covered by this plan"},"before_reserved_cost":{"type":"number","description":"Hourly cost from current/existing reservations for this resource"},"after_reserved_cost":{"type":"number","description":"Hourly commitment/reserved cost after applying this plan"},"before_cost":{"type":"number","description":"Total hourly cost before applying this plan (ondemand + reserved costs)"},"after_cost":{"type":"number","description":"Total hourly cost after applying this plan"},"monthly_before_cost":{"type":"number","description":"Total monthly cost before applying this plan"},"monthly_after_cost":{"type":"number","description":"Total monthly cost after applying this plan"},"monthly_after_reserved_cost":{"type":"number","description":"Monthly reserved/commitment cost portion after applying this plan"},"monthly_after_ondemand_cost":{"type":"number","description":"Monthly ondemand cost portion after applying this plan"},"average_savings":{"type":"number","description":"Average hourly savings from this plan"},"average_monthly_savings":{"type":"number","description":"Average monthly savings from this plan"},"usage_type":{"description":"Type of resource usage","type":"string","enum":["running","resource","requests","gb_seconds","gb_hours","cpu_hours","cpu_utilization","os_hours","units_per_month","gb_per_month","provisioned_concurrency_gb_seconds","provisioned_duration_gb_seconds","unknown"]},"coverage":{"type":"number","description":"Percentage of total units that will be covered by commitments (0-1)"},"resource":{"description":"Detailed resource information including provider, service, and instance details etc","anyOf":[{"$ref":"#/components/schemas/ResourceSKU"},{"type":"null"}]}},"required":["after_cost","after_covered_units","after_ondemand_cost","after_reserved_cost","after_uncovered_units","average_monthly_savings","average_savings","before_cost","before_ondemand_cost","before_reserved_cost","before_uncovered_units","coverage","covered_ondemand_cost","id","if_all_ondemand_cost","monthly_after_cost","monthly_after_ondemand_cost","monthly_after_reserved_cost","monthly_before_cost","ondemand_price","resource","total_units","usage_type"],"additionalProperties":false},"ResourceSKU":{"type":"object","properties":{"id":{"type":"string"},"resource_id":{"type":"string","format":"uuid","description":"Unique identifier for the underlying resource"},"provider":{"type":"string","enum":["aws","azure","gcp"]},"provider_resource_id":{"type":"string","description":"Provider's unique identifier (e.g., ARN for AWS)"},"is_spot":{"type":"boolean","description":"Whether this is a spot instance (a way to utilize unused instances)"},"name":{"type":["string","null"]},"resource_group":{"type":["string","null"],"description":"Azure resource group"},"usage_end":{"type":"string","format":"date","description":"Last date this resource had usage"},"usage_start":{"type":"string","format":"date","description":"First date this resource had usage"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string","format":"date"},"updated_at":{"type":"string","format":"date"},"instance_id":{"readOnly":true,"type":"string"},"billing_account_id":{"type":"string","description":"Management account ID (AWS) or billing account ID (Azure/GCP)"},"sub_account_id":{"type":"string","description":"Account ID where the resource is running"},"management_account_id":{"readOnly":true,"description":"Management account ID (AWS) or billing account ID (Azure/GCP)","deprecated":true,"type":"string"},"owner_account_id":{"readOnly":true,"description":"Account ID where the resource is running","deprecated":true,"type":"string"},"sku_title":{"readOnly":true,"type":"string"},"sku_name":{"type":["string","null"]},"availability_zone":{"type":["string","null"]},"cache_engine":{"type":["string","null"],"description":"Cache engine type (e.g., Redis, Memcached)"},"database_engine":{"type":["string","null"],"description":"Database engine type (e.g., MySQL, PostgreSQL)"},"description":{"type":["string","null"]},"family":{"type":["string","null"],"description":"Service or product family (e.g., 'Compute', 'Storage')"},"full_region_name":{"type":["string","null"]},"has_ondemand_terms":{"type":["boolean","null"],"description":"Whether on-demand pricing is available for this SKU"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g., 'm5.large', 'Standard_D4s_v3')"},"instance_type_family":{"type":["string","null"],"description":"Instance family (e.g., 'm5', 'Standard_D')"},"is_reservable":{"type":["boolean","null"],"description":"Whether this resource type supports reservations/commitments"},"license_model":{"type":["string","null"]},"location_type":{"type":["string","null"]},"normalization_size_factor":{"type":["string","null"]},"operating_system":{"type":["string","null"]},"pre_installed_sw":{"type":["string","null"]},"price_currency":{"type":["string","null"]},"provider_service":{"type":["string","null"]},"provider_sku_id":{"type":["string","null"]},"publication_date":{"type":["string","null"]},"region":{"type":["string","null"]},"service":{"type":["string","null"],"description":"Service name (e.g., 'Amazon Elastic Compute Cloud')"},"tenancy":{"type":["string","null"]},"usage_type":{"type":["string","null"]},"version":{"type":["string","null"]},"vpc_networking_support":{"type":["boolean","null"]},"ondemand_usage_unit":{"type":["string","null"]}},"required":["billing_account_id","created_at","id","is_spot","management_account_id","owner_account_id","provider","provider_resource_id","resource_id","sub_account_id","tags","updated_at","usage_end","usage_start"],"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /commitment-plans/{plan\_id}/comparison

> Returns per-line-item offer alternatives plus plan-wide rollups for each (contract\_term, payment\_option) hypothetical. Designed to answer 'what would the plan look like at 3-year' in a single call: hypothetical\_totals carries the rolled-up financials and delta\_vs\_current, with per-line-item resolution exposed for transparency. Each line item lands at the target term when available, else the longest available term <= target with the same payment option (GRI preferred within tier), else its current term. Defaults: line\_item\_ids=all selected, contract\_terms=all distinct in candidates, payment\_options=\[no\_upfront].

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans","description":"API for managing commitment plans"}],"paths":{"/v1/org/{org_id}/commitment-plans/{plan_id}/comparison":{"get":{"parameters":[{"in":"query","name":"line_item_ids","description":"Optional subset of line items to compare. If omitted, defaults to all selected line items in the plan.","schema":{"type":["array","null"],"default":null,"items":{"type":"string","format":"uuid"}},"required":false,"explode":true,"style":"form"},{"in":"query","name":"contract_terms","description":"Optional list of target terms to roll up. If omitted, the response includes a hypothetical for every distinct contract_term that appears in any line item's candidates after the payment-option filter.","schema":{"type":["array","null"],"default":null,"items":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]}},"required":false,"explode":true,"style":"form"},{"in":"query","name":"payment_options","description":"Payment options to include. Defaults to no_upfront only — most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Pass partial_upfront / all_upfront explicitly to surface those.","schema":{"type":"array","items":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":false,"explode":true,"style":"form"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LineItemOfferComparisonResponse"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans"],"summary":"/commitment-plans/{plan_id}/comparison","description":"Returns per-line-item offer alternatives plus plan-wide rollups for each (contract_term, payment_option) hypothetical. Designed to answer 'what would the plan look like at 3-year' in a single call: hypothetical_totals carries the rolled-up financials and delta_vs_current, with per-line-item resolution exposed for transparency. Each line item lands at the target term when available, else the longest available term <= target with the same payment option (GRI preferred within tier), else its current term. Defaults: line_item_ids=all selected, contract_terms=all distinct in candidates, payment_options=[no_upfront]."}}},"components":{"schemas":{"LineItemOfferComparisonResponse":{"type":"object","properties":{"current_totals":{"description":"Plan-wide totals for the line items currently in scope (defaults to all selected, narrowed by line_item_ids if provided). Use this as the baseline when interpreting hypothetical deltas.","$ref":"#/components/schemas/LineItemOfferComparisonTotals"},"hypothetical_totals":{"type":"array","description":"One entry per (contract_term, payment_option) combination requested (or per distinct term present in candidates if contract_terms was omitted). Each entry's totals + delta_vs_current answer 'what's the plan-wide impact of this term?' in one place — no client-side summing across line items required.","items":{"$ref":"#/components/schemas/HypotheticalTotal"}},"data":{"type":"array","description":"Per-line-item detail. Use when the user wants to drill into 'why does RDS not have a 3-year candidate' or to assemble an update payload.","items":{"$ref":"#/components/schemas/LineItemOfferComparisonRow"}}},"required":["current_totals","data","hypothetical_totals"],"additionalProperties":false},"LineItemOfferComparisonTotals":{"type":"object","properties":{"commitment_financials_monthly_rate":{"description":"730-hour monthly rate financials summed across the line items in scope. Same shape as on plans / line items.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars at signing across the line items in scope. NOT a rate — do not sum with monthly-rate fields."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"HypotheticalTotal":{"type":"object","properties":{"contract_term":{"description":"Target contract term for this hypothetical.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"payment_option":{"description":"Target payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"description":"Rolled-up monthly-rate financials assuming each line item adopts its candidate per the fallback rule. Same shape as on plans / line items.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars across the line items under this hypothetical. NOT a rate."},"delta_vs_current":{"description":"Axis-by-axis difference vs current_totals. The headline 'should I do this' answer is delta_vs_current.monthly_net_savings.","$ref":"#/components/schemas/HypotheticalDelta"},"line_items":{"type":"array","description":"Per-line-item resolution for this hypothetical. Use to call out fallbacks ('14 of 20 line items would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current').","items":{"$ref":"#/components/schemas/HypotheticalLineItem"}}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","line_items","payment_option"],"additionalProperties":false},"HypotheticalDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the plan does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"HypotheticalLineItem":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"actual_term":{"description":"The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"actual_payment_option":{"description":"Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."}},"required":["actual_payment_option","actual_term","actual_term_reason","line_item_id"],"additionalProperties":false},"LineItemOfferComparisonRow":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"current":{"description":"The line item's current offer + lease, in the same shape as OfferComparisonEntrySchema. Its delta_vs_current is all zeros.","$ref":"#/components/schemas/OfferComparisonEntry"},"candidates":{"type":"array","description":"Alternative (offer, lease) pairs for this line item, filtered to the requested contract_terms and payment_options. Each entry carries its own contract_term and payment_option (on offer); fields offer_id, lease_menu_item_id, and selected_amount can be copied verbatim into POST /commitment-plans/{plan_id}/line-items/update (in the `updates` list) to swap the line item to that candidate.","items":{"$ref":"#/components/schemas/OfferComparisonEntry"}}},"required":["candidates","current","line_item_id"],"additionalProperties":false},"OfferComparisonEntry":{"type":"object","properties":{"is_current":{"type":"boolean","description":"True if this entry matches the line item's current offer + lease. Exactly one entry per response has this set; its `delta_vs_current` values are all zero."},"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","$ref":"#/components/schemas/CommitmentOffer"},"lease_menu_item_id":{"type":["string","null"],"format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`."},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":["number","null"],"description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost)."},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","$ref":"#/components/schemas/OfferComparisonDelta"}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","is_current","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5'), null for some commitment types"},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"product_description":{"type":["string","null"],"description":"Product description (e.g. 'Linux/UNIX')"},"display_name":{"type":["string","null"],"description":"Human-readable offer name"},"guaranteed_display_name":{"type":["string","null"],"description":"Offer name when purchased as an Archera Guaranteed Commitment"},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":["number","null"],"description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven."}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Commitments

API for retrieving and analyzing cloud commitment inventory, including Reserved Instances, Savings Plans, and Azure Reserved VM Instances. Provides access to detailed commitment data, utilization metrics, and cost savings information.

## /commitments

> Retrieves a paginated list of commitments for the specified organization and time period. Returns detailed information about each commitment including utilization, savings, and status. Results can be filtered by provider, search term, and custom criteria, and sorted by various attributes.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitments","description":"API for retrieving and analyzing cloud commitment inventory, including Reserved Instances, Savings Plans, and Azure Reserved VM Instances. Provides access to detailed commitment data, utilization metrics, and cost savings information."}],"paths":{"/v1/org/{org_id}/commitments":{"get":{"parameters":[{"in":"query","name":"search","description":"Text to search across multiple columns (case-insensitive partial match)","schema":{"type":"string"},"required":false},{"in":"query","name":"filter","description":"JSON object specifying field-specific filter criteria","schema":{"type":["object","null"],"additionalProperties":{}},"required":false},{"in":"query","name":"desc","description":"Sort in descending order if true","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by","schema":{"type":["string","null"],"default":"end_date","enum":["duration_seconds","start_date","end_date","upfront_cost","amortized_cost","recurring_cost","created_at","updated_at","is_leased","account_id","type","status","scope","reservation_end","utilization","monthly_savings",null]},"required":false},{"in":"query","name":"provider","description":"Cloud provider to filter commitments by","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"start_date","description":"Start date for the commitment period (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date for the commitment period (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":10,"minimum":1,"maximum":10000},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicCommitment"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments"],"summary":"/commitments","description":"Retrieves a paginated list of commitments for the specified organization and time period. Returns detailed information about each commitment including utilization, savings, and status. Results can be filtered by provider, search term, and custom criteria, and sorted by various attributes."}}},"components":{"schemas":{"PublicCommitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string"},"leased_display_name":{"type":"string"},"provider_reservation_id":{"type":"string"},"account_id":{"type":["string","null"]},"master_account_id":{"readOnly":true,"deprecated":true,"type":["string","null"]},"billing_account_id":{"type":["string","null"]},"type":{"type":"string"},"region":{"type":["string","null"]},"duration_seconds":{"type":["integer","null"]},"reservation_end":{"type":["string","null"]},"reservation_start":{"type":["string","null"]},"transfer_reservation_start":{"type":["string","null"],"format":"date-time"},"transfer_reservation_end":{"type":["string","null"],"format":"date-time"},"start_date":{"type":["string","null"],"format":"date-time"},"end_date":{"type":["string","null"],"format":"date-time"},"status":{"enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_leased":{"type":"boolean"},"is_active":{"type":"boolean"},"lease":{"anyOf":[{"$ref":"#/components/schemas/LeaseMenuItem"},{"type":"null"}]},"lease_start":{"type":["string","null"],"format":"date-time"},"lease_lockin_date":{"type":["string","null"],"format":"date-time"},"upfront_cost":{"type":"number"},"recurring_cost":{"type":"number"},"is_flexible":{"type":["boolean","null"]},"payment_option":{"enum":["No Upfront","Partial Upfront","All Upfront",null]},"offering_class":{"enum":["standard","convertible",null]},"offering_id":{"type":["string","null"]},"instance_count":{"type":["integer","null"]},"effective_instance_count":{"type":["integer","null"]},"product_description":{"type":["string","null"]},"instance_family":{"type":["string","null"]},"instance_type":{"type":["string","null"]},"tenancy":{"type":["string","null"]},"az":{"type":["string","null"]},"is_multi_az":{"type":["boolean","null"]},"plan_type":{"type":["string","null"]},"scope":{"enum":["shared","subscription","resource_group","management_group",null]},"name":{"type":["string","null"]},"order_id":{"type":["string","null"]},"resource_group":{"type":["string","null"]},"instance_flexibility":{"type":["boolean","null"]},"savings":{"type":["number","null"]},"monthly_savings":{"type":["number","null"]},"net_savings":{"type":["number","null"]},"utilization":{"type":["number","null"]},"potential_savings":{"type":["number","null"]},"running_hours":{"type":["number","null"]},"amortized_cost":{"type":["number","null"]},"daily_utilizations":{"type":"array","items":{"$ref":"#/components/schemas/DailyUtilization"}}},"required":["account_id","amortized_cost","az","billing_account_id","daily_utilizations","display_name","duration_seconds","effective_instance_count","end_date","id","instance_count","instance_family","instance_flexibility","instance_type","is_active","is_flexible","is_leased","is_multi_az","lease","lease_lockin_date","lease_start","leased_display_name","master_account_id","monthly_savings","name","net_savings","offering_class","offering_id","order_id","payment_option","plan_type","potential_savings","product_description","provider","provider_reservation_id","recurring_cost","region","reservation_end","reservation_start","resource_group","running_hours","savings","scope","start_date","status","tenancy","transfer_reservation_end","transfer_reservation_start","type","upfront_cost","utilization"],"additionalProperties":false},"LeaseMenuItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fee_type":{"type":"string"},"fee_rate":{"type":"number"},"is_rebate":{"type":"boolean"},"lockin_months":{"type":"integer"},"term_months":{"type":"integer"}},"required":["fee_rate","fee_type","is_rebate","lockin_months","term_months"],"additionalProperties":false},"DailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date"},"reservation_utilization":{"type":"number"},"covered_cost":{"type":"number"},"cost":{"type":"number"},"potential_savings":{"type":["number","null"]},"running_hours":{"type":["number","null"]},"savings":{"type":"number"},"unutilized_commit":{"type":"number"},"gri_fees":{"type":"number"},"net_savings":{"type":"number"}},"required":["cost","covered_cost","date","gri_fees","net_savings","potential_savings","reservation_utilization","running_hours","savings","unutilized_commit"],"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## GET /v1/org/{org\_id}/commitments/ids

>

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitments","description":"API for retrieving and analyzing cloud commitment inventory, including Reserved Instances, Savings Plans, and Azure Reserved VM Instances. Provides access to detailed commitment data, utilization metrics, and cost savings information."}],"paths":{"/v1/org/{org_id}/commitments/ids":{"get":{"parameters":[{"in":"query","name":"search","description":"Text to search across multiple columns (case-insensitive partial match)","schema":{"type":"string"},"required":false},{"in":"query","name":"filter","description":"JSON object specifying field-specific filter criteria","schema":{"type":["object","null"],"additionalProperties":{}},"required":false},{"in":"query","name":"desc","description":"Sort in descending order if true","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by","schema":{"type":["string","null"],"default":"end_date","enum":["duration_seconds","start_date","end_date","upfront_cost","amortized_cost","recurring_cost","created_at","updated_at","is_leased","account_id","type","status","scope","reservation_end","utilization","monthly_savings",null]},"required":false},{"in":"query","name":"provider","description":"Cloud provider to filter commitments by","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"start_date","description":"Start date for the commitment period (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date for the commitment period (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments"]}}},"components":{"schemas":{"IdsResponse":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}}},"required":["ids"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /commitments/chart

> Generates time-series chart data for commitment metrics over the specified time period. The data includes daily or monthly values for commitment spend, utilization, locked vs unlocked commitments, and realized savings. Results are aggregated by day or month depending on the date range selected. \
> \
> \*\*Future Projections:\*\* When the end\_date extends into the future, the API returns projected values based on current commitment utilization patterns. Each data point includes an \`is\_projection\` field that indicates whether the values are historical (false) or projected (true). Projected values assume that active commitments will continue with their current utilization rates through their expiration dates. This is useful for forecasting future commitment costs and savings based on existing commitments.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Commitments","description":"API for retrieving and analyzing cloud commitment inventory, including Reserved Instances, Savings Plans, and Azure Reserved VM Instances. Provides access to detailed commitment data, utilization metrics, and cost savings information."}],"paths":{"/v1/org/{org_id}/commitments/chart":{"get":{"parameters":[{"in":"query","name":"filter","description":"Optional JSON filter criteria for commitment data","schema":{"type":["object","null"],"additionalProperties":{}},"required":false},{"in":"query","name":"provider","description":"Cloud provider to filter commitments by","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"start_date","description":"Start date for the chart data (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date for the chart data (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PubChartResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments"],"summary":"/commitments/chart","description":"Generates time-series chart data for commitment metrics over the specified time period. The data includes daily or monthly values for commitment spend, utilization, locked vs unlocked commitments, and realized savings. Results are aggregated by day or month depending on the date range selected. \n\n**Future Projections:** When the end_date extends into the future, the API returns projected values based on current commitment utilization patterns. Each data point includes an `is_projection` field that indicates whether the values are historical (false) or projected (true). Projected values assume that active commitments will continue with their current utilization rates through their expiration dates. This is useful for forecasting future commitment costs and savings based on existing commitments."}}},"components":{"schemas":{"PubChartResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DataPoint"}}},"additionalProperties":false},"DataPoint":{"type":"object","properties":{"date":{"type":"string"},"remaining_commit":{"type":"number"},"locked_commit":{"type":"number"},"unlocked_commit":{"type":"number"},"savings":{"type":"number"},"net_savings":{"type":"number"},"utilization":{"type":"number"},"unutilized_commit":{"type":"number"},"is_projection":{"type":"boolean","description":"Indicates whether this data point is a projection based on current commitment utilization patterns. Historical data (is_projection=false) reflects actual recorded metrics, while projected data (is_projection=true) represents estimated future values assuming commitments continue with their current utilization rates."}},"required":["date","is_projection","locked_commit","net_savings","remaining_commit","savings","unlocked_commit","unutilized_commit","utilization"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Exchanges

API for commitment exchange recommendations

## Get Azure exchange recommendations

> Returns Azure reservation exchange recommendations using the same recommendation logic as the beta exchange endpoint, including plan-derived exchanges and eligible same-SKU 1-year native to 1-year GRI exchanges. When plan\_id is omitted, the endpoint prefers the latest calculated 'Recommended RIs Only' default plan for the provider-resources segment (a twin of the Recommended plan without savings plans, which cannot be exchanged), falling back to the Recommended default plan when that plan does not exist yet. Currently only provider=azure is supported.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Exchanges","description":"API for commitment exchange recommendations"}],"paths":{"/v1/org/{org_id}/exchanges/recommendations":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"plan_id","description":"Optional commitment plan ID to use for plan-derived exchange purchases. When omitted, the endpoint prefers the latest calculated 'Recommended RIs Only' default plan for the provider-resources segment — a twin of the Recommended plan without savings plans, which cannot be exchanged — falling back to the same Recommended default plan selected by GET /commitment-plans/recommended when that plan does not exist yet. Responses may also include non-plan-derived native-to-GRI exchanges.","schema":{"type":["string","null"],"format":"uuid","default":null},"required":false},{"in":"query","name":"commitment_ids","description":"Optional explicit Azure commitment IDs to consider returning. When omitted, the exchanger detects underutilized exchange candidates from the default 3-day DailyUtilization lookback. Explicit commitments without utilization rows in that lookback are excluded. Mutually exclusive with plan_id.","schema":{"type":["array","null"],"default":null,"items":{"type":"string","format":"uuid"}},"required":false,"explode":true,"style":"form"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeRecommendationsResponse"}}}},"204":{"description":"No Content"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Exchanges"],"summary":"Get Azure exchange recommendations","description":"Returns Azure reservation exchange recommendations using the same recommendation logic as the beta exchange endpoint, including plan-derived exchanges and eligible same-SKU 1-year native to 1-year GRI exchanges. When plan_id is omitted, the endpoint prefers the latest calculated 'Recommended RIs Only' default plan for the provider-resources segment (a twin of the Recommended plan without savings plans, which cannot be exchanged), falling back to the Recommended default plan when that plan does not exist yet. Currently only provider=azure is supported."}}},"components":{"schemas":{"ExchangeRecommendationsResponse":{"type":"object","properties":{"current_utilization_lookback_days":{"type":"integer","description":"Number of trailing days of DailyUtilization used for returned-commitment utilization and financials."},"data":{"type":"array","description":"Azure exchange recommendations.","items":{"$ref":"#/components/schemas/ExchangeRecommendation"}}},"required":["current_utilization_lookback_days","data"],"additionalProperties":false},"ExchangeRecommendation":{"type":"object","properties":{"purchase_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value of the purchase side."},"returned_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value returned by the exchange."},"additional_lifetime_commitment":{"type":"number","description":"Purchase lifetime commitment minus returned lifetime commitment. Azure exchange policy requires this to be non-negative."},"purchase":{"$ref":"#/components/schemas/ExchangePurchase"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeReturn"}},"purchase_commitment_financials_monthly_rate":{"description":"Purchase-side monthly-rate financials.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"returned_commitment_financials_monthly_rate":{"description":"Returned commitments' rolled-up monthly-rate financials for the selected integer return quantities. Cost comes from DailyUtilization commitment cost, and savings are computed after assigning as much utilization as possible to the quantity that remains committed. Rebate and Archera premium are excluded from exchange recommendations and are not included in net savings.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"returned_commitment_daily_utilizations":{"type":"array","description":"Daily whole-commitment utilization for the returned commitments, dollar weighted by each return's commitment cost. Use this for exchange-level utilization charts.","items":{"$ref":"#/components/schemas/ExchangeReturnedCommitmentDailyUtilization"}},"reason":{"type":["string","null"],"description":"Short human-readable reason this exchange was recommended, based on how the exchanger generated it."},"delta_vs_returned":{"description":"Purchase-side economics compared with returned-commitment economics. Monthly fields are purchase-side minus returned-side; purchase_upfront_cost is purchase-side one-time upfront only and is not netted. Purchase financials come from plan-amortized line item financials; returned financials come from DailyUtilization cost and covered usage for the selected integer return quantities, normalized to 730-hour monthly rates.","$ref":"#/components/schemas/ExchangeRecommendationDelta"}},"required":["additional_lifetime_commitment","delta_vs_returned","purchase","purchase_commitment_financials_monthly_rate","purchase_lifetime_commitment","returned_commitment_daily_utilizations","returned_commitment_financials_monthly_rate","returned_lifetime_commitment","returns"],"additionalProperties":false},"ExchangePurchase":{"type":"object","properties":{"account_id":{"type":["string","null"],"description":"Target cloud account/subscription for the purchase."},"contract_term":{"description":"User-facing purchase commitment term. For leased/guaranteed purchases this is the lease lock-in term; for native purchases it is the offer duration.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"lease_menu_item_id":{"type":["string","null"],"format":"uuid","description":"Lease menu item attached to the purchase side, or null for native purchases."},"quantity":{"type":"integer","description":"Quantity of the Azure reservation to purchase."},"offer":{"description":"Azure reservation offer being purchased.","$ref":"#/components/schemas/CommitmentOffer"},"commitment_upfront_cost":{"type":"number","description":"One-time upfront dollars required at signing for the purchase side. NOT a monthly rate."},"commitment_financials_monthly_rate":{"description":"Purchase-side plan line item economics as 730-hour monthly rates.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","offer","quantity"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5'), null for some commitment types"},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"product_description":{"type":["string","null"],"description":"Product description (e.g. 'Linux/UNIX')"},"display_name":{"type":["string","null"],"description":"Human-readable offer name"},"guaranteed_display_name":{"type":["string","null"],"description":"Offer name when purchased as an Archera Guaranteed Commitment"},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"ExchangeReturn":{"type":"object","properties":{"commitment":{"description":"Azure commitment proposed to return in the exchange.","$ref":"#/components/schemas/Commitment"},"quantity":{"type":"integer","description":"Quantity of this commitment proposed for return."},"remaining_lifetime_commitment":{"type":"number","description":"Remaining Azure commitment value returned for this commitment quantity. This is lifetime exchange value, not a monthly rate."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitment over the DailyUtilization period (0-1)."},"underutilized_commitment_cost":{"type":"number","description":"Estimated underutilized commitment cost over the DailyUtilization period. This is a period total, not a monthly rate."},"utilization_days":{"type":"integer","description":"Number of DailyUtilization days behind the utilization fields."},"reservation_resource_id":{"type":"string","description":"Azure reservation resource ID required by Azure exchange APIs."},"commitment_financials_monthly_rate":{"description":"Returned commitment economics as a 730-hour monthly rate for the selected integer return quantity. Cost comes from DailyUtilization commitment cost for the response period, scaled to the returned quantity. Savings are computed after assigning as much utilization as possible to the quantity that remains committed, so returned fully-utilized quantities can have positive savings and underutilized quantities have negative savings. Archera premium and rebate are excluded from exchange recommendations and are not included in net savings.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}},"required":["commitment","commitment_financials_monthly_rate","quantity","remaining_lifetime_commitment","reservation_resource_id","underutilized_commitment_cost","utilization","utilization_days"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":["string","null"],"description":"Cloud account ID this commitment is in"},"billing_account_id":{"type":["string","null"],"description":"Billing/management account ID"},"start_date":{"type":["string","null"],"format":"date-time","description":"When the commitment started"},"end_date":{"type":["string","null"],"format":"date-time","description":"When the commitment expires"},"duration_seconds":{"type":["integer","null"],"description":"Total commitment duration in seconds"},"guarantee_start":{"type":["string","null"],"format":"date-time","description":"When the Archera guarantee period started"},"guarantee_lockin_date":{"type":["string","null"],"format":"date-time","description":"When the Archera guarantee lock-in period ends"},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge')"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5')"},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"},"instance_count":{"type":["integer","null"],"description":"Number of instances covered"},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]}},"required":["id","provider"],"additionalProperties":false},"ExchangeReturnedCommitmentDailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"DailyUtilization date."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitments for this date (0-1), dollar weighted by each return's commitment cost."}},"required":["date","utilization"],"additionalProperties":false},"ExchangeRecommendationDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Purchase monthly net savings minus returned commitments' monthly net savings. Positive means the exchange purchase saves more per 730-hour month."},"monthly_commitment_cost":{"type":"number","description":"Purchase monthly commitment cost minus returned commitments' monthly commitment cost. Positive means more monthly commitment spend."},"purchase_upfront_cost":{"type":"number","description":"Purchase-side one-time upfront cost only. Not netted against returned commitments because returned financials are monthly-rate utilization actuals and have no upfront component. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","purchase_upfront_cost"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Apply Azure exchange recommendations

> Requests application of one Azure reservation exchange recommendation using the same explicit purchase and return item body as the beta exchange endpoint. Currently only provider=azure is supported.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Exchanges","description":"API for commitment exchange recommendations"}],"paths":{"/v1/org/{org_id}/exchanges/recommendations/apply":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyExchangeRecommendationsResponse"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyExchangeRecommendationsArgs"}}}},"tags":["Exchanges"],"summary":"Apply Azure exchange recommendations","description":"Requests application of one Azure reservation exchange recommendation using the same explicit purchase and return item body as the beta exchange endpoint. Currently only provider=azure is supported."}}},"components":{"schemas":{"ApplyExchangeRecommendationsResponse":{"type":"object","properties":{"status":{"type":"string","description":"Application status for the exchange recommendations."},"recommendation_count":{"type":"integer","description":"Number of exchange recommendations applied."}},"required":["recommendation_count","status"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"ApplyExchangeRecommendationsArgs":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"purchases":{"type":"array","minItems":1,"description":"Explicit purchase-side line items for one exchange recommendation.","items":{"$ref":"#/components/schemas/ApplyExchangePurchase"}},"returns":{"type":"array","minItems":1,"description":"Explicit return-side line items for one exchange recommendation.","items":{"$ref":"#/components/schemas/ApplyExchangeReturn"}}},"required":["provider","purchases","returns"],"additionalProperties":false},"ApplyExchangePurchase":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Azure reservation offer ID to purchase."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this offer to purchase."}},"required":["offer_id","quantity"],"additionalProperties":false},"ApplyExchangeReturn":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Existing Azure commitment ID to return."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this commitment to return."}},"required":["commitment_id","quantity"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Metrics

High level metrics to track commitment performance.

## /metrics

> Retrieves key performance metrics for cloud commitments (RIs/SPs) for the specified provider. Returns financial data including lifetime and month-to-date savings, automation status, potential missed savings opportunities, commitment coverage, and utilization rates. This endpoint provides a comprehensive overview of commitment performance and automation status.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Metrics","description":"High level metrics to track commitment performance."}],"paths":{"/v1/org/{org_id}/metrics":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider to get metrics for","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicMetrics"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Metrics"],"summary":"/metrics","description":"Retrieves key performance metrics for cloud commitments (RIs/SPs) for the specified provider. Returns financial data including lifetime and month-to-date savings, automation status, potential missed savings opportunities, commitment coverage, and utilization rates. This endpoint provides a comprehensive overview of commitment performance and automation status."}}},"components":{"schemas":{"PublicMetrics":{"type":"object","properties":{"lifetime_savings":{"type":"number"},"lifetime_gri_savings":{"type":"number"},"mtd_savings":{"type":"number"},"mtd_gri_savings":{"type":"number"},"purchase_automation_enabled":{"type":"boolean"},"buyback_automation_enabled":{"type":"boolean"},"has_actioned_plan":{"type":"boolean"},"has_pending_actions":{"type":"boolean"},"latest_execution_date":{"type":"string","format":"date"},"purchase_missed_savings":{"type":"number"},"buyback_missed_savings":{"type":"number"},"total_daily_missed_savings":{"type":"number"},"hourly_missed_savings":{"type":"number"},"missed_savings_start_date":{"type":"string","format":"date"},"missed_savings_end_date":{"type":"string","format":"date"},"expiring_savings":{"type":"number"},"coverage":{"type":"number"},"utilization":{"type":"number"}},"required":["buyback_automation_enabled","buyback_missed_savings","coverage","expiring_savings","has_actioned_plan","has_pending_actions","hourly_missed_savings","latest_execution_date","lifetime_gri_savings","lifetime_savings","missed_savings_end_date","missed_savings_start_date","mtd_gri_savings","mtd_savings","purchase_automation_enabled","purchase_missed_savings","total_daily_missed_savings","utilization"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Orgs

Endpoints for organizations accessible to the authenticated user

## List accessible organizations

> Returns the list of organizations that the authenticated user has access to. This includes:\
> \
> \- Organizations where the user is a direct member (kind: 'direct')\
> \- Child organizations if the user belongs to a partner organization (kind: 'partnership')\
> \- All active organizations if the user is an Archera staff member (kind: 'staff')\
> \
> Each organization includes the user's role and membership kind.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Orgs","description":"Endpoints for organizations accessible to the authenticated user"}],"paths":{"/v1/orgs":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Org"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"List accessible organizations","description":"Returns the list of organizations that the authenticated user has access to. This includes:\n\n- Organizations where the user is a direct member (kind: 'direct')\n- Child organizations if the user belongs to a partner organization (kind: 'partnership')\n- All active organizations if the user is an Archera staff member (kind: 'staff')\n\nEach organization includes the user's role and membership kind.","tags":["Orgs"]}}},"components":{"schemas":{"Org":{"type":"object","properties":{"org_id":{"type":"string","pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z","description":"Unique organization identifier"},"name":{"type":"string","description":"Organization name"},"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"],"description":"User's role in the organization (e.g., admin, user, support, cloud_rep, restricted_user)"},"kind":{"description":"Type of membership: 'direct' (direct member), 'partnership' (via partner org), 'staff' (Archera staff)","enum":["direct","staff","partnership"]}},"required":["kind","name","org_id","role"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Resources

API for retrieving and analyzing infrastructure resources

## /resources

> Retrieves a list of infrastructure resources for the organization, including compute instances, databases, and other services with their current status and costs.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Resources","description":"API for retrieving and analyzing infrastructure resources"}],"paths":{"/v1/org/{org_id}/resources":{"get":{"parameters":[{"in":"query","name":"provider","description":"Filter by provider","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":false},{"in":"query","name":"segment_id","description":"Filter by segment ID","schema":{"type":"string","format":"uuid"},"required":false},{"in":"query","name":"search","description":"Text to search across multiple columns (case-insensitive partial match)","schema":{"type":"string"},"required":false},{"in":"query","name":"desc","description":"Sort in descending order if true","schema":{"type":["boolean","null"],"default":null},"required":false},{"in":"query","name":"order_by","description":"Field to order results by","schema":{"type":["string","null"],"default":"id","enum":["id","usage_start",null]},"required":false},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ResourceSKU"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Resources"],"summary":"/resources","description":"Retrieves a list of infrastructure resources for the organization, including compute instances, databases, and other services with their current status and costs."}}},"components":{"schemas":{"ResourceSKU":{"type":"object","properties":{"id":{"type":"string"},"resource_id":{"type":"string","format":"uuid","description":"Unique identifier for the underlying resource"},"provider":{"type":"string","enum":["aws","azure","gcp"]},"provider_resource_id":{"type":"string","description":"Provider's unique identifier (e.g., ARN for AWS)"},"is_spot":{"type":"boolean","description":"Whether this is a spot instance (a way to utilize unused instances)"},"name":{"type":["string","null"]},"resource_group":{"type":["string","null"],"description":"Azure resource group"},"usage_end":{"type":"string","format":"date","description":"Last date this resource had usage"},"usage_start":{"type":"string","format":"date","description":"First date this resource had usage"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string","format":"date"},"updated_at":{"type":"string","format":"date"},"instance_id":{"readOnly":true,"type":"string"},"billing_account_id":{"type":"string","description":"Management account ID (AWS) or billing account ID (Azure/GCP)"},"sub_account_id":{"type":"string","description":"Account ID where the resource is running"},"management_account_id":{"readOnly":true,"description":"Management account ID (AWS) or billing account ID (Azure/GCP)","deprecated":true,"type":"string"},"owner_account_id":{"readOnly":true,"description":"Account ID where the resource is running","deprecated":true,"type":"string"},"sku_title":{"readOnly":true,"type":"string"},"sku_name":{"type":["string","null"]},"availability_zone":{"type":["string","null"]},"cache_engine":{"type":["string","null"],"description":"Cache engine type (e.g., Redis, Memcached)"},"database_engine":{"type":["string","null"],"description":"Database engine type (e.g., MySQL, PostgreSQL)"},"description":{"type":["string","null"]},"family":{"type":["string","null"],"description":"Service or product family (e.g., 'Compute', 'Storage')"},"full_region_name":{"type":["string","null"]},"has_ondemand_terms":{"type":["boolean","null"],"description":"Whether on-demand pricing is available for this SKU"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g., 'm5.large', 'Standard_D4s_v3')"},"instance_type_family":{"type":["string","null"],"description":"Instance family (e.g., 'm5', 'Standard_D')"},"is_reservable":{"type":["boolean","null"],"description":"Whether this resource type supports reservations/commitments"},"license_model":{"type":["string","null"]},"location_type":{"type":["string","null"]},"normalization_size_factor":{"type":["string","null"]},"operating_system":{"type":["string","null"]},"pre_installed_sw":{"type":["string","null"]},"price_currency":{"type":["string","null"]},"provider_service":{"type":["string","null"]},"provider_sku_id":{"type":["string","null"]},"publication_date":{"type":["string","null"]},"region":{"type":["string","null"]},"service":{"type":["string","null"],"description":"Service name (e.g., 'Amazon Elastic Compute Cloud')"},"tenancy":{"type":["string","null"]},"usage_type":{"type":["string","null"]},"version":{"type":["string","null"]},"vpc_networking_support":{"type":["boolean","null"]},"ondemand_usage_unit":{"type":["string","null"]}},"required":["billing_account_id","created_at","id","is_spot","management_account_id","owner_account_id","provider","provider_resource_id","resource_id","sub_account_id","tags","updated_at","usage_end","usage_start"],"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /resources/{resource\_id}/daily-usage

> Retrieves daily usage data for a specific resource within the specified date range. Optionally filter by catalog\_sku\_id to get usage for a specific SKU. Including usage metrics, costs, and coverage information.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Resources","description":"API for retrieving and analyzing infrastructure resources"}],"paths":{"/v1/org/{org_id}/resources/{resource_id}/daily-usage":{"get":{"parameters":[{"in":"query","name":"start_date","description":"Start date for the date range filter (inclusive)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date for the date range filter (inclusive)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"catalog_sku_id","description":"Optional catalog SKU ID to filter daily usage records for a specific SKU","schema":{"type":["string","null"],"format":"uuid"},"required":false},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":100,"minimum":1,"maximum":10000},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SKUUsageDaily"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Resources"],"summary":"/resources/{resource_id}/daily-usage","description":"Retrieves daily usage data for a specific resource within the specified date range. Optionally filter by catalog_sku_id to get usage for a specific SKU. Including usage metrics, costs, and coverage information."}}},"components":{"schemas":{"SKUUsageDaily":{"type":"object","properties":{"date":{"type":"string","format":"date"},"usage_account_id":{"readOnly":true,"deprecated":true,"type":"string"},"sub_account_id":{"type":"string"},"usage":{"type":"number"},"reservation_usage":{"type":"number"},"free_tier_usage":{"type":"number"},"ondemand_cost":{"type":"number"},"reserved_cost":{"type":"number"},"if_all_ondemand_cost":{"type":"number"},"spot_cost":{"type":"number"},"free_tier_savings":{"type":"number"},"usage_type":{"type":["string","null"]},"common_usage_type":{"type":["string","null"]},"covered_usage":{"type":"number"},"uptime":{"type":"number"}},"required":["common_usage_type","covered_usage","date","free_tier_savings","free_tier_usage","if_all_ondemand_cost","ondemand_cost","reservation_usage","reserved_cost","spot_cost","sub_account_id","uptime","usage","usage_account_id","usage_type"],"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Savings Estimate

API for estimating savings from uploaded billing files

## Estimate savings from an uploaded billing file

> Parses a completed PDF, CSV, JSON, or text billing upload and returns normalized costs and provider-specific savings estimates.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Savings Estimate","description":"API for estimating savings from uploaded billing files"}],"paths":{"/v1/org/{org_id}/savings-estimate":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsEstimate"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsEstimateRequest"}}}},"tags":["Savings Estimate"],"summary":"Estimate savings from an uploaded billing file","description":"Parses a completed PDF, CSV, JSON, or text billing upload and returns normalized costs and provider-specific savings estimates."}}},"components":{"schemas":{"SavingsEstimate":{"type":"object","properties":{"provider":{"type":["string","null"],"enum":["aws","azure","gcp",null]},"source_format":{"type":"string"},"period_start":{"type":["string","null"],"format":"date"},"period_end":{"type":["string","null"],"format":"date"},"account_id":{"type":["string","null"]},"currency":{"type":"string"},"is_projected":{"type":"boolean"},"extraction_status":{"enum":["complete","partial","unverified"]},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/CostLineItem"}},"total_cost":{"readOnly":true,"$ref":"#/components/schemas/ValueRange"},"total_savings_estimate":{"readOnly":true,"$ref":"#/components/schemas/ValueRange"}},"required":["account_id","currency","extraction_status","is_projected","line_items","period_end","period_start","provider","source_format","total_cost","total_savings_estimate"],"additionalProperties":false},"CostLineItem":{"type":"object","properties":{"service":{"type":"string"},"reservable_service":{"type":["string","null"]},"resource_type":{"type":["string","null"]},"usage_quantity":{"anyOf":[{"$ref":"#/components/schemas/ValueRange"},{"type":"null"}]},"usage_unit":{"type":["string","null"]},"cost":{"$ref":"#/components/schemas/ValueRange"},"region":{"type":["string","null"]},"spend_type":{"enum":["on_demand","reserved","unreservable","unknown"]},"savings_estimate":{"anyOf":[{"$ref":"#/components/schemas/ValueRange"},{"type":"null"}]}},"required":["cost","region","reservable_service","resource_type","savings_estimate","service","spend_type","usage_quantity","usage_unit"],"additionalProperties":false},"ValueRange":{"type":"object","properties":{"estimate":{"type":"number"},"lower_bound":{"type":["number","null"]},"upper_bound":{"type":["number","null"]}},"required":["estimate","lower_bound","upper_bound"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"SavingsEstimateRequest":{"type":"object","properties":{"upload_id":{"type":"string","format":"uuid"}},"required":["upload_id"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Uploads

API for uploading billing files for savings estimates

## Upload a billing file for a savings estimate

> Accepts a multipart PDF, CSV, JSON, or text billing file, stores it in Archera's invoice upload bucket, and returns an upload ID. Use this upload ID with the savings-estimate operation. The upload status workflow is: PENDING before storage begins, PROCESSING while the file is being transferred, COMPLETE once it is available for analysis, and ERROR if storage fails.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Uploads","description":"API for uploading billing files for savings estimates"}],"paths":{"/v1/org/{org_id}/uploads":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUpload"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreatePublicUpload"}}}},"tags":["Uploads"],"summary":"Upload a billing file for a savings estimate","description":"Accepts a multipart PDF, CSV, JSON, or text billing file, stores it in Archera's invoice upload bucket, and returns an upload ID. Use this upload ID with the savings-estimate operation. The upload status workflow is: PENDING before storage begins, PROCESSING while the file is being transferred, COMPLETE once it is available for analysis, and ERROR if storage fails."}}},"components":{"schemas":{"PublicUpload":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"org_id":{"type":"string","readOnly":true,"maxLength":50},"file_name":{"type":"string","readOnly":true,"maxLength":255},"content_type":{"type":"string","readOnly":true,"maxLength":255},"size_bytes":{"type":"integer","readOnly":true},"description":{"type":["string","null"],"readOnly":true,"maxLength":255},"upload_status":{"readOnly":true,"type":"string","enum":["PENDING","PROCESSING","COMPLETE","ERROR"]},"source":{"readOnly":true,"enum":["agent_upload","attachment","partner_api"]},"detected_type":{"type":["string","null"],"readOnly":true,"maxLength":64},"available_actions":{"type":"array","readOnly":true,"items":{"enum":["savings_estimate"]}}},"required":["content_type","created_at","description","detected_type","file_name","id","org_id","size_bytes","source","upload_status"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"CreatePublicUpload":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255,"description":"Optional partner-supplied context for the uploaded billing file"},"file":{"writeOnly":true,"description":"Billing PDF, CSV, JSON, or text file to upload for a savings estimate","type":"string","format":"binary"}},"required":["file"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get uploaded billing file status

> Returns metadata and upload status for a partner API upload. Clients can poll this endpoint until upload\_status is COMPLETE, then pass the upload ID to the savings-estimate operation.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Uploads","description":"API for uploading billing files for savings estimates"}],"paths":{"/v1/org/{org_id}/uploads/{upload_id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicUpload"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Uploads"],"summary":"Get uploaded billing file status","description":"Returns metadata and upload status for a partner API upload. Clients can poll this endpoint until upload_status is COMPLETE, then pass the upload ID to the savings-estimate operation."}}},"components":{"schemas":{"PublicUpload":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"org_id":{"type":"string","readOnly":true,"maxLength":50},"file_name":{"type":"string","readOnly":true,"maxLength":255},"content_type":{"type":"string","readOnly":true,"maxLength":255},"size_bytes":{"type":"integer","readOnly":true},"description":{"type":["string","null"],"readOnly":true,"maxLength":255},"upload_status":{"readOnly":true,"type":"string","enum":["PENDING","PROCESSING","COMPLETE","ERROR"]},"source":{"readOnly":true,"enum":["agent_upload","attachment","partner_api"]},"detected_type":{"type":["string","null"],"readOnly":true,"maxLength":64},"available_actions":{"type":"array","readOnly":true,"items":{"enum":["savings_estimate"]}}},"required":["content_type","created_at","description","detected_type","file_name","id","org_id","size_bytes","source","upload_status"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Well Known

OAuth 2.0 discovery endpoints (JWKS and Authorization Server Metadata)

## /.well-known/jwks.json

> Returns the JSON Web Key Set (JWKS) containing public keys used to verify JWT tokens issued by Archera. This endpoint follows the RFC 7517 standard for JWK and is used by clients to validate JWT signatures. No authentication is required as this endpoint provides public cryptographic keys.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Well-Known","description":"OAuth 2.0 discovery endpoints (JWKS and Authorization Server Metadata)"}],"paths":{"/.well-known/jwks.json":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JWKS"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Failed to load keys"},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Well-Known"],"summary":"/.well-known/jwks.json","description":"Returns the JSON Web Key Set (JWKS) containing public keys used to verify JWT tokens issued by Archera. This endpoint follows the RFC 7517 standard for JWK and is used by clients to validate JWT signatures. No authentication is required as this endpoint provides public cryptographic keys."}}},"components":{"schemas":{"JWKS":{"type":"object","properties":{"keys":{"type":"array","description":"Array of JSON Web Keys","items":{"$ref":"#/components/schemas/JWK"}}},"required":["keys"],"additionalProperties":false},"JWK":{"type":"object","properties":{"kty":{"type":"string","description":"Key type (e.g., 'RSA')"},"use":{"type":"string","description":"Public key use (e.g., 'sig' for signature)"},"kid":{"type":"string","description":"Key ID for identifying the key"},"alg":{"type":"string","description":"Algorithm (e.g., 'RS256')"},"n":{"type":"string","description":"RSA modulus (base64url encoded)"},"e":{"type":"string","description":"RSA public exponent (base64url encoded)"}},"required":["alg","e","kid","kty","n","use"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /.well-known/oauth-authorization-server

> Returns OAuth 2.0 Authorization Server Metadata as specified in RFC 8414. This endpoint provides automatic discovery of the authorization server's configuration, including supported endpoints, grant types, response types, PKCE methods, and available scopes. OAuth client libraries can use this endpoint to automatically configure themselves without manual endpoint configuration. No authentication is required as this is a public discovery endpoint.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Well-Known","description":"OAuth 2.0 discovery endpoints (JWKS and Authorization Server Metadata)"}],"paths":{"/.well-known/oauth-authorization-server":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthMetadata"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Well-Known"],"summary":"/.well-known/oauth-authorization-server","description":"Returns OAuth 2.0 Authorization Server Metadata as specified in RFC 8414. This endpoint provides automatic discovery of the authorization server's configuration, including supported endpoints, grant types, response types, PKCE methods, and available scopes. OAuth client libraries can use this endpoint to automatically configure themselves without manual endpoint configuration. No authentication is required as this is a public discovery endpoint."}}},"components":{"schemas":{"OAuthMetadata":{"type":"object","properties":{"issuer":{"type":"string","description":"The authorization server's issuer identifier URL"},"authorization_endpoint":{"type":"string","description":"URL of the OAuth 2.0 authorization endpoint"},"token_endpoint":{"type":"string","description":"URL of the OAuth 2.0 token endpoint"},"revocation_endpoint":{"type":"string","description":"URL of the OAuth 2.0 token revocation endpoint (RFC 7009)"},"registration_endpoint":{"type":"string","description":"URL of the OAuth 2.0 dynamic client registration endpoint (RFC 7591)"},"jwks_uri":{"type":"string","description":"URL of the JSON Web Key Set document"},"response_types_supported":{"type":"array","description":"OAuth 2.0 response_type values supported","items":{"type":"string"}},"grant_types_supported":{"type":"array","description":"OAuth 2.0 grant type values supported","items":{"type":"string"}},"code_challenge_methods_supported":{"type":"array","description":"PKCE code challenge methods supported","items":{"type":"string"}},"token_endpoint_auth_methods_supported":{"type":"array","description":"Client authentication methods supported at token endpoint","items":{"type":"string"}},"scopes_supported":{"type":"array","description":"OAuth 2.0 scope values supported","items":{"type":"string"}},"service_documentation":{"type":"string","description":"URL of service documentation for developers"}},"required":["authorization_endpoint","code_challenge_methods_supported","grant_types_supported","issuer","jwks_uri","registration_endpoint","response_types_supported","revocation_endpoint","scopes_supported","token_endpoint","token_endpoint_auth_methods_supported"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# OAuth

OAuth 2.0 authorization endpoints for third-party integrations

## Redirect to React consent page.

> Query Parameters (handled by Authlib):\
> &#x20;   client\_id: OAuth client identifier\
> &#x20;   redirect\_uri: Where to redirect after authorization\
> &#x20;   response\_type: Must be 'code'\
> &#x20;   scope: Space-separated list of requested scopes\
> &#x20;   state: CSRF protection token (optional but recommended)\
> &#x20;   code\_challenge: PKCE code challenge\
> &#x20;   code\_challenge\_method: PKCE method (usually 'S256')\
> \
> Returns:\
> &#x20;   Redirect to React consent page with OAuth params and client info

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/authorize":{"get":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Redirect to React consent page.","description":"Query Parameters (handled by Authlib):\n    client_id: OAuth client identifier\n    redirect_uri: Where to redirect after authorization\n    response_type: Must be 'code'\n    scope: Space-separated list of requested scopes\n    state: CSRF protection token (optional but recommended)\n    code_challenge: PKCE code challenge\n    code_challenge_method: PKCE method (usually 'S256')\n\nReturns:\n    Redirect to React consent page with OAuth params and client info","tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Handle user authorization decision from React consent page.

> Query Parameters:\
> &#x20;   All OAuth params from GET (client\_id, redirect\_uri, state, etc.)\
> \
> Form Parameters:\
> &#x20;   confirm: 'yes' to authorize, 'no' to deny\
> \
> Returns:\
> &#x20;   Redirect to client with authorization code or error

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/authorize":{"post":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Handle user authorization decision from React consent page.","description":"Query Parameters:\n    All OAuth params from GET (client_id, redirect_uri, state, etc.)\n\nForm Parameters:\n    confirm: 'yes' to authorize, 'no' to deny\n\nReturns:\n    Redirect to client with authorization code or error","tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Issue access tokens.

> Form Parameters (authorization\_code grant):\
> &#x20;   grant\_type: Must be 'authorization\_code'\
> &#x20;   code: Authorization code from /authorize\
> &#x20;   redirect\_uri: Must match original request\
> &#x20;   client\_id: OAuth client identifier\
> &#x20;   code\_verifier: PKCE code verifier\
> \
> Form Parameters (refresh\_token grant):\
> &#x20;   grant\_type: Must be 'refresh\_token'\
> &#x20;   refresh\_token: Valid refresh token\
> &#x20;   client\_id: OAuth client identifier\
> \
> Returns:\
> &#x20;   JSON response with access\_token (JWT), refresh\_token, expires\_in, etc.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/token":{"post":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Issue access tokens.","description":"Form Parameters (authorization_code grant):\n    grant_type: Must be 'authorization_code'\n    code: Authorization code from /authorize\n    redirect_uri: Must match original request\n    client_id: OAuth client identifier\n    code_verifier: PKCE code verifier\n\nForm Parameters (refresh_token grant):\n    grant_type: Must be 'refresh_token'\n    refresh_token: Valid refresh token\n    client_id: OAuth client identifier\n\nReturns:\n    JSON response with access_token (JWT), refresh_token, expires_in, etc.","tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## List all active OAuth sessions for the current user.

> Returns:\
> List of active sessions including client info, creation time, and scope

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/sessions":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OAuthSessionResponse"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"List all active OAuth sessions for the current user.","description":"Returns:\nList of active sessions including client info, creation time, and scope","tags":["OAuth"]}}},"components":{"schemas":{"OAuthSessionResponse":{"type":"object","properties":{"token_id":{"type":"string","pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"client_name":{"type":"string"},"client_id":{"type":"string"},"created_at":{"type":"integer"},"scope":{"type":"string"}},"required":["client_id","client_name","created_at","scope","token_id"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Revoke a specific OAuth session by token ID.

> Args:\
> &#x20;   token\_id: UUID of the OAuth token to revoke\
> \
> Returns:\
> &#x20;   204 No Content on success\
> &#x20;   404 Not Found if session doesn't exist or doesn't belong to user

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/sessions/{token_id}":{"delete":{"responses":{"204":{"description":"No Content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Revoke a specific OAuth session by token ID.","description":"Args:\n    token_id: UUID of the OAuth token to revoke\n\nReturns:\n    204 No Content on success\n    404 Not Found if session doesn't exist or doesn't belong to user","tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Revoke all OAuth sessions (refresh tokens) for the current user across all clients.

> Returns:\
> JSON with message and count of revoked sessions

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/revoke-all":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeAllSessionsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Revoke all OAuth sessions (refresh tokens) for the current user across all clients.","description":"Returns:\nJSON with message and count of revoked sessions","tags":["OAuth"]}}},"components":{"schemas":{"RevokeAllSessionsResponse":{"type":"object","properties":{"message":{"type":"string"},"count":{"type":"integer"}},"required":["count","message"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Revoke an access token or refresh token.

> Form Parameters:\
> &#x20;   token: The token to revoke (access\_token or refresh\_token)\
> &#x20;   token\_type\_hint: Optional hint about token type ('access\_token' or 'refresh\_token')\
> \
> Returns:\
> &#x20;   200 response (always returns 200 per RFC 7009, even for invalid tokens)

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/revoke":{"post":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Revoke an access token or refresh token.","description":"Form Parameters:\n    token: The token to revoke (access_token or refresh_token)\n    token_type_hint: Optional hint about token type ('access_token' or 'refresh_token')\n\nReturns:\n    200 response (always returns 200 per RFC 7009, even for invalid tokens)","tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## POST /oauth/register

>

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"OAuth","description":"OAuth 2.0 authorization endpoints for third-party integrations"}],"paths":{"/oauth/register":{"post":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["OAuth"]}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Models

## The Error object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}}}
```

## The PaginationMetadata object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false}}}}
```

## The ApiErrorResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]}}}}
```

## The CommitmentPlan object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CommitmentPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"org_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"is_calculating":{"type":"boolean"},"status":{"enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"max_term":{"type":["string","null"]},"covered_ondemand_cost_hourly":{"type":"number"},"before_ondemand_cost_hourly":{"type":"number"},"before_reserved_cost_hourly":{"type":"number"},"amortized_cost_hourly":{"type":"number"},"recurring_cost_hourly":{"type":"number"},"upfront_cost_hourly":{"type":"number"},"before_cost_hourly":{"type":"number"},"after_cost_hourly":{"type":"number"},"total_cost_hourly":{"type":"number"},"savings_hourly":{"type":"number"},"fee_hourly":{"type":"number"},"commitment_coverage":{"type":"number"},"minimum_commitment_cost":{"type":"number"},"breakeven_hours":{"type":"number"},"total_savings":{"type":"number"},"monthly_savings":{"type":"number"},"total_monthly_before_cost":{"type":"number"}},"required":["after_cost_hourly","amortized_cost_hourly","before_cost_hourly","before_ondemand_cost_hourly","before_reserved_cost_hourly","breakeven_hours","commitment_coverage","covered_ondemand_cost_hourly","created_at","fee_hourly","id","is_calculating","max_term","minimum_commitment_cost","monthly_savings","name","org_id","recurring_cost_hourly","savings_hourly","status","total_cost_hourly","total_monthly_before_cost","total_savings","upfront_cost_hourly"],"additionalProperties":false}}}}
```

## The PurchasePlanContractSpec object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"PurchasePlanContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string"},"properties":{"type":"object","default":{},"additionalProperties":{}},"term":{"default":null,"type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"payment_option":{"default":null,"type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]}},"required":["commitment_type"],"additionalProperties":false}}}}
```

## The PublicCommitmentOffer object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"PublicCommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["aws","azure","gcp"]},"provider_offering_id":{"type":"string"},"type":{"type":"string"},"display_name":{"type":["string","null"]},"leased_display_name":{"type":["string","null"]},"region":{"type":["string","null"]},"duration_seconds":{"type":"number"},"upfront_cost":{"type":"number"},"recurring_cost":{"type":"number"},"offering_class":{"enum":["standard","convertible",null]},"payment_option":{"enum":["No Upfront","Partial Upfront","All Upfront",null]},"offering_id":{"type":["string","null"]},"product_description":{"type":["string","null"]},"instance_family":{"type":["string","null"]},"instance_type":{"type":["string","null"]},"tenancy":{"type":["string","null"]},"az":{"type":["string","null"]},"is_multi_az":{"type":["boolean","null"]},"is_flexible":{"type":["boolean","null"]},"plan_type":{"type":["string","null"]}},"required":["az","display_name","duration_seconds","id","instance_family","instance_type","is_flexible","is_multi_az","leased_display_name","offering_id","plan_type","product_description","provider","provider_offering_id","recurring_cost","region","tenancy","type","upfront_cost"],"additionalProperties":false}}}}
```

## The CommitmentPlanLineItem\_Exclude\_CoveredServices object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CommitmentPlanLineItem_Exclude_CoveredServices":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"plan_id":{"type":"string","format":"uuid"},"offer_id":{"type":"string","format":"uuid"},"lease_menu_item_id":{"type":["string","null"],"format":"uuid"},"account_id":{"type":["string","null"]},"recommended_quantity":{"type":"integer","description":"Recommended number of units to purchase"},"selected_quantity":{"type":"integer","description":"Selected number of units to purchase"},"recommended_commitment":{"type":"number","description":"Recommended hourly commitment amount ($/hour for Savings Plans, 0 for instance RIs)"},"selected_commitment":{"type":"number","description":"Selected hourly commitment amount ($/hour for Savings Plans, 0 for instance RIs)"},"is_selected":{"type":"boolean","description":"Whether this line item is selected for purchase"},"after_amortized_cost":{"type":"number","description":"Hourly amortized cost of the commitment (upfront + recurring)"},"upfront_cost":{"type":"number","description":"Total upfront payment required (not hourly rate)"},"recurring_cost":{"type":"number","description":"Hourly recurring cost"},"before_cost":{"type":"number","description":"Total hourly cost before this commitment (ondemand + existing reservations)"},"before_ondemand_cost":{"type":"number","description":"Hourly ondemand cost before this commitment"},"before_reserved_cost":{"type":"number","description":"Hourly reserved cost from existing commitments"},"covered_ondemand_cost":{"type":"number","description":"Hourly ondemand cost that will be covered by this commitment"},"after_covered_units":{"type":"number","description":"Units that will be covered after the plan is applied"},"total_cost":{"type":"number","description":"Total cost of this commitment over its full term"},"monthly_cost":{"type":"number","description":"Monthly cost of this commitment"},"savings":{"type":"number","description":"Hourly savings compared to ondemand pricing"},"monthly_savings":{"type":"number","description":"Average monthly savings compared to ondemand pricing"},"total_savings":{"type":"number","description":"Total savings over the commitment term"},"fee":{"type":"number","description":"Estimated Archera premium (hourly) based on quoted maximum savings. See https://www.archera.ai/pricing for details."},"discount_rate":{"type":"number","description":"Discount percentage vs ondemand"},"breakeven_hours":{"type":"number","description":"Hours of usage needed until the achieved savings is greater than the remaining commitment for this line item"},"contract_term":{"description":"Commitment term (e.g., 'one_year_gris', 'thirty_day_gris')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment structure (No Upfront, Partial Upfront, All Upfront)","enum":["No Upfront","Partial Upfront","All Upfront"]},"contract_spec":{"description":"Detailed contract specifications including commitment type and properties","$ref":"#/components/schemas/PurchasePlanContractSpec"},"offer":{"description":"Detailed information about the commitment offer","$ref":"#/components/schemas/PublicCommitmentOffer"}},"required":["account_id","after_amortized_cost","after_covered_units","before_cost","before_ondemand_cost","before_reserved_cost","breakeven_hours","contract_spec","contract_term","covered_ondemand_cost","discount_rate","fee","id","is_selected","lease_menu_item_id","monthly_cost","monthly_savings","offer","offer_id","payment_option","plan_id","recommended_commitment","recommended_quantity","recurring_cost","savings","selected_commitment","selected_quantity","total_cost","total_savings","upfront_cost"],"additionalProperties":false},"PurchasePlanContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string"},"properties":{"type":"object","default":{},"additionalProperties":{}},"term":{"default":null,"type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"payment_option":{"default":null,"type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]}},"required":["commitment_type"],"additionalProperties":false},"PublicCommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["aws","azure","gcp"]},"provider_offering_id":{"type":"string"},"type":{"type":"string"},"display_name":{"type":["string","null"]},"leased_display_name":{"type":["string","null"]},"region":{"type":["string","null"]},"duration_seconds":{"type":"number"},"upfront_cost":{"type":"number"},"recurring_cost":{"type":"number"},"offering_class":{"enum":["standard","convertible",null]},"payment_option":{"enum":["No Upfront","Partial Upfront","All Upfront",null]},"offering_id":{"type":["string","null"]},"product_description":{"type":["string","null"]},"instance_family":{"type":["string","null"]},"instance_type":{"type":["string","null"]},"tenancy":{"type":["string","null"]},"az":{"type":["string","null"]},"is_multi_az":{"type":["boolean","null"]},"is_flexible":{"type":["boolean","null"]},"plan_type":{"type":["string","null"]}},"required":["az","display_name","duration_seconds","id","instance_family","instance_type","is_flexible","is_multi_az","leased_display_name","offering_id","plan_type","product_description","provider","provider_offering_id","recurring_cost","region","tenancy","type","upfront_cost"],"additionalProperties":false}}}}
```

## The ResourceSKU object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ResourceSKU":{"type":"object","properties":{"id":{"type":"string"},"resource_id":{"type":"string","format":"uuid","description":"Unique identifier for the underlying resource"},"provider":{"type":"string","enum":["aws","azure","gcp"]},"provider_resource_id":{"type":"string","description":"Provider's unique identifier (e.g., ARN for AWS)"},"is_spot":{"type":"boolean","description":"Whether this is a spot instance (a way to utilize unused instances)"},"name":{"type":["string","null"]},"resource_group":{"type":["string","null"],"description":"Azure resource group"},"usage_end":{"type":"string","format":"date","description":"Last date this resource had usage"},"usage_start":{"type":"string","format":"date","description":"First date this resource had usage"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string","format":"date"},"updated_at":{"type":"string","format":"date"},"instance_id":{"readOnly":true,"type":"string"},"billing_account_id":{"type":"string","description":"Management account ID (AWS) or billing account ID (Azure/GCP)"},"sub_account_id":{"type":"string","description":"Account ID where the resource is running"},"management_account_id":{"readOnly":true,"description":"Management account ID (AWS) or billing account ID (Azure/GCP)","deprecated":true,"type":"string"},"owner_account_id":{"readOnly":true,"description":"Account ID where the resource is running","deprecated":true,"type":"string"},"sku_title":{"readOnly":true,"type":"string"},"sku_name":{"type":["string","null"]},"availability_zone":{"type":["string","null"]},"cache_engine":{"type":["string","null"],"description":"Cache engine type (e.g., Redis, Memcached)"},"database_engine":{"type":["string","null"],"description":"Database engine type (e.g., MySQL, PostgreSQL)"},"description":{"type":["string","null"]},"family":{"type":["string","null"],"description":"Service or product family (e.g., 'Compute', 'Storage')"},"full_region_name":{"type":["string","null"]},"has_ondemand_terms":{"type":["boolean","null"],"description":"Whether on-demand pricing is available for this SKU"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g., 'm5.large', 'Standard_D4s_v3')"},"instance_type_family":{"type":["string","null"],"description":"Instance family (e.g., 'm5', 'Standard_D')"},"is_reservable":{"type":["boolean","null"],"description":"Whether this resource type supports reservations/commitments"},"license_model":{"type":["string","null"]},"location_type":{"type":["string","null"]},"normalization_size_factor":{"type":["string","null"]},"operating_system":{"type":["string","null"]},"pre_installed_sw":{"type":["string","null"]},"price_currency":{"type":["string","null"]},"provider_service":{"type":["string","null"]},"provider_sku_id":{"type":["string","null"]},"publication_date":{"type":["string","null"]},"region":{"type":["string","null"]},"service":{"type":["string","null"],"description":"Service name (e.g., 'Amazon Elastic Compute Cloud')"},"tenancy":{"type":["string","null"]},"usage_type":{"type":["string","null"]},"version":{"type":["string","null"]},"vpc_networking_support":{"type":["boolean","null"]},"ondemand_usage_unit":{"type":["string","null"]}},"required":["billing_account_id","created_at","id","is_spot","management_account_id","owner_account_id","provider","provider_resource_id","resource_id","sub_account_id","tags","updated_at","usage_end","usage_start"],"additionalProperties":false}}}}
```

## The CommitmentPlanResourceMatch object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CommitmentPlanResourceMatch":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the resource match"},"total_units":{"type":"number","description":"Total resource usage units"},"before_uncovered_units":{"type":"number","description":"Units not covered at the moment (before this plan)"},"after_covered_units":{"type":"number","description":"Units that will be covered after the plan is applied"},"after_uncovered_units":{"type":"number","description":"Units that will remain uncovered after the plan to avoid overcommit"},"ondemand_price":{"type":"number","description":"Ondemand cost per unit-hour"},"if_all_ondemand_cost":{"type":"number","description":"Hourly cost if paying all the units with ondemand price"},"before_ondemand_cost":{"type":"number","description":"Current hourly ondemand cost for units not covered by existing commitments"},"after_ondemand_cost":{"type":"number","description":"Hourly ondemand cost remaining after applying this plan"},"covered_ondemand_cost":{"type":"number","description":"Hourly ondemand cost for units that will be covered by this plan"},"before_reserved_cost":{"type":"number","description":"Hourly cost from current/existing reservations for this resource"},"after_reserved_cost":{"type":"number","description":"Hourly commitment/reserved cost after applying this plan"},"before_cost":{"type":"number","description":"Total hourly cost before applying this plan (ondemand + reserved costs)"},"after_cost":{"type":"number","description":"Total hourly cost after applying this plan"},"monthly_before_cost":{"type":"number","description":"Total monthly cost before applying this plan"},"monthly_after_cost":{"type":"number","description":"Total monthly cost after applying this plan"},"monthly_after_reserved_cost":{"type":"number","description":"Monthly reserved/commitment cost portion after applying this plan"},"monthly_after_ondemand_cost":{"type":"number","description":"Monthly ondemand cost portion after applying this plan"},"average_savings":{"type":"number","description":"Average hourly savings from this plan"},"average_monthly_savings":{"type":"number","description":"Average monthly savings from this plan"},"usage_type":{"description":"Type of resource usage","type":"string","enum":["running","resource","requests","gb_seconds","gb_hours","cpu_hours","cpu_utilization","os_hours","units_per_month","gb_per_month","provisioned_concurrency_gb_seconds","provisioned_duration_gb_seconds","unknown"]},"coverage":{"type":"number","description":"Percentage of total units that will be covered by commitments (0-1)"},"resource":{"description":"Detailed resource information including provider, service, and instance details etc","anyOf":[{"$ref":"#/components/schemas/ResourceSKU"},{"type":"null"}]}},"required":["after_cost","after_covered_units","after_ondemand_cost","after_reserved_cost","after_uncovered_units","average_monthly_savings","average_savings","before_cost","before_ondemand_cost","before_reserved_cost","before_uncovered_units","coverage","covered_ondemand_cost","id","if_all_ondemand_cost","monthly_after_cost","monthly_after_ondemand_cost","monthly_after_reserved_cost","monthly_before_cost","ondemand_price","resource","total_units","usage_type"],"additionalProperties":false},"ResourceSKU":{"type":"object","properties":{"id":{"type":"string"},"resource_id":{"type":"string","format":"uuid","description":"Unique identifier for the underlying resource"},"provider":{"type":"string","enum":["aws","azure","gcp"]},"provider_resource_id":{"type":"string","description":"Provider's unique identifier (e.g., ARN for AWS)"},"is_spot":{"type":"boolean","description":"Whether this is a spot instance (a way to utilize unused instances)"},"name":{"type":["string","null"]},"resource_group":{"type":["string","null"],"description":"Azure resource group"},"usage_end":{"type":"string","format":"date","description":"Last date this resource had usage"},"usage_start":{"type":"string","format":"date","description":"First date this resource had usage"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string","format":"date"},"updated_at":{"type":"string","format":"date"},"instance_id":{"readOnly":true,"type":"string"},"billing_account_id":{"type":"string","description":"Management account ID (AWS) or billing account ID (Azure/GCP)"},"sub_account_id":{"type":"string","description":"Account ID where the resource is running"},"management_account_id":{"readOnly":true,"description":"Management account ID (AWS) or billing account ID (Azure/GCP)","deprecated":true,"type":"string"},"owner_account_id":{"readOnly":true,"description":"Account ID where the resource is running","deprecated":true,"type":"string"},"sku_title":{"readOnly":true,"type":"string"},"sku_name":{"type":["string","null"]},"availability_zone":{"type":["string","null"]},"cache_engine":{"type":["string","null"],"description":"Cache engine type (e.g., Redis, Memcached)"},"database_engine":{"type":["string","null"],"description":"Database engine type (e.g., MySQL, PostgreSQL)"},"description":{"type":["string","null"]},"family":{"type":["string","null"],"description":"Service or product family (e.g., 'Compute', 'Storage')"},"full_region_name":{"type":["string","null"]},"has_ondemand_terms":{"type":["boolean","null"],"description":"Whether on-demand pricing is available for this SKU"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g., 'm5.large', 'Standard_D4s_v3')"},"instance_type_family":{"type":["string","null"],"description":"Instance family (e.g., 'm5', 'Standard_D')"},"is_reservable":{"type":["boolean","null"],"description":"Whether this resource type supports reservations/commitments"},"license_model":{"type":["string","null"]},"location_type":{"type":["string","null"]},"normalization_size_factor":{"type":["string","null"]},"operating_system":{"type":["string","null"]},"pre_installed_sw":{"type":["string","null"]},"price_currency":{"type":["string","null"]},"provider_service":{"type":["string","null"]},"provider_sku_id":{"type":["string","null"]},"publication_date":{"type":["string","null"]},"region":{"type":["string","null"]},"service":{"type":["string","null"],"description":"Service name (e.g., 'Amazon Elastic Compute Cloud')"},"tenancy":{"type":["string","null"]},"usage_type":{"type":["string","null"]},"version":{"type":["string","null"]},"vpc_networking_support":{"type":["boolean","null"]},"ondemand_usage_unit":{"type":["string","null"]}},"required":["billing_account_id","created_at","id","is_spot","management_account_id","owner_account_id","provider","provider_resource_id","resource_id","sub_account_id","tags","updated_at","usage_end","usage_start"],"additionalProperties":false}}}}
```

## The CloudProviderCostBreakdown object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false}}}}
```

## The CloudProviderCost object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false}}}}
```

## The CommitmentCostBreakdown object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false}}}}
```

## The CommitmentCost object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false}}}}
```

## The CommitmentSavings\_Exclude\_Rebate object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The CommitmentFinancialsNoRebate object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The LineItemOfferComparisonTotals object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"LineItemOfferComparisonTotals":{"type":"object","properties":{"commitment_financials_monthly_rate":{"description":"730-hour monthly rate financials summed across the line items in scope. Same shape as on plans / line items.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars at signing across the line items in scope. NOT a rate — do not sum with monthly-rate fields."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The HypotheticalDelta object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"HypotheticalDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the plan does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The HypotheticalLineItem object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"HypotheticalLineItem":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"actual_term":{"description":"The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"actual_payment_option":{"description":"Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."}},"required":["actual_payment_option","actual_term","actual_term_reason","line_item_id"],"additionalProperties":false}}}}
```

## The HypotheticalTotal object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"HypotheticalTotal":{"type":"object","properties":{"contract_term":{"description":"Target contract term for this hypothetical.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"payment_option":{"description":"Target payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"description":"Rolled-up monthly-rate financials assuming each line item adopts its candidate per the fallback rule. Same shape as on plans / line items.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars across the line items under this hypothetical. NOT a rate."},"delta_vs_current":{"description":"Axis-by-axis difference vs current_totals. The headline 'should I do this' answer is delta_vs_current.monthly_net_savings.","$ref":"#/components/schemas/HypotheticalDelta"},"line_items":{"type":"array","description":"Per-line-item resolution for this hypothetical. Use to call out fallbacks ('14 of 20 line items would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current').","items":{"$ref":"#/components/schemas/HypotheticalLineItem"}}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","line_items","payment_option"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"HypotheticalDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the plan does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"HypotheticalLineItem":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"actual_term":{"description":"The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"actual_payment_option":{"description":"Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."}},"required":["actual_payment_option","actual_term","actual_term_reason","line_item_id"],"additionalProperties":false}}}}
```

## The CommitmentOffer object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5'), null for some commitment types"},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"product_description":{"type":["string","null"],"description":"Product description (e.g. 'Linux/UNIX')"},"display_name":{"type":["string","null"],"description":"Human-readable offer name"},"guaranteed_display_name":{"type":["string","null"],"description":"Offer name when purchased as an Archera Guaranteed Commitment"},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"}},"additionalProperties":false}}}}
```

## The OfferComparisonDelta object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":["number","null"],"description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven."}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The OfferComparisonEntry object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"OfferComparisonEntry":{"type":"object","properties":{"is_current":{"type":"boolean","description":"True if this entry matches the line item's current offer + lease. Exactly one entry per response has this set; its `delta_vs_current` values are all zero."},"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","$ref":"#/components/schemas/CommitmentOffer"},"lease_menu_item_id":{"type":["string","null"],"format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`."},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":["number","null"],"description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost)."},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","$ref":"#/components/schemas/OfferComparisonDelta"}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","is_current","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5'), null for some commitment types"},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"product_description":{"type":["string","null"],"description":"Product description (e.g. 'Linux/UNIX')"},"display_name":{"type":["string","null"],"description":"Human-readable offer name"},"guaranteed_display_name":{"type":["string","null"],"description":"Offer name when purchased as an Archera Guaranteed Commitment"},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":["number","null"],"description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven."}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The LineItemOfferComparisonRow object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"LineItemOfferComparisonRow":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"current":{"description":"The line item's current offer + lease, in the same shape as OfferComparisonEntrySchema. Its delta_vs_current is all zeros.","$ref":"#/components/schemas/OfferComparisonEntry"},"candidates":{"type":"array","description":"Alternative (offer, lease) pairs for this line item, filtered to the requested contract_terms and payment_options. Each entry carries its own contract_term and payment_option (on offer); fields offer_id, lease_menu_item_id, and selected_amount can be copied verbatim into POST /commitment-plans/{plan_id}/line-items/update (in the `updates` list) to swap the line item to that candidate.","items":{"$ref":"#/components/schemas/OfferComparisonEntry"}}},"required":["candidates","current","line_item_id"],"additionalProperties":false},"OfferComparisonEntry":{"type":"object","properties":{"is_current":{"type":"boolean","description":"True if this entry matches the line item's current offer + lease. Exactly one entry per response has this set; its `delta_vs_current` values are all zero."},"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","$ref":"#/components/schemas/CommitmentOffer"},"lease_menu_item_id":{"type":["string","null"],"format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`."},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":["number","null"],"description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost)."},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","$ref":"#/components/schemas/OfferComparisonDelta"}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","is_current","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5'), null for some commitment types"},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"product_description":{"type":["string","null"],"description":"Product description (e.g. 'Linux/UNIX')"},"display_name":{"type":["string","null"],"description":"Human-readable offer name"},"guaranteed_display_name":{"type":["string","null"],"description":"Offer name when purchased as an Archera Guaranteed Commitment"},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":["number","null"],"description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven."}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The LineItemOfferComparisonResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"LineItemOfferComparisonResponse":{"type":"object","properties":{"current_totals":{"description":"Plan-wide totals for the line items currently in scope (defaults to all selected, narrowed by line_item_ids if provided). Use this as the baseline when interpreting hypothetical deltas.","$ref":"#/components/schemas/LineItemOfferComparisonTotals"},"hypothetical_totals":{"type":"array","description":"One entry per (contract_term, payment_option) combination requested (or per distinct term present in candidates if contract_terms was omitted). Each entry's totals + delta_vs_current answer 'what's the plan-wide impact of this term?' in one place — no client-side summing across line items required.","items":{"$ref":"#/components/schemas/HypotheticalTotal"}},"data":{"type":"array","description":"Per-line-item detail. Use when the user wants to drill into 'why does RDS not have a 3-year candidate' or to assemble an update payload.","items":{"$ref":"#/components/schemas/LineItemOfferComparisonRow"}}},"required":["current_totals","data","hypothetical_totals"],"additionalProperties":false},"LineItemOfferComparisonTotals":{"type":"object","properties":{"commitment_financials_monthly_rate":{"description":"730-hour monthly rate financials summed across the line items in scope. Same shape as on plans / line items.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars at signing across the line items in scope. NOT a rate — do not sum with monthly-rate fields."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"HypotheticalTotal":{"type":"object","properties":{"contract_term":{"description":"Target contract term for this hypothetical.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"payment_option":{"description":"Target payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"description":"Rolled-up monthly-rate financials assuming each line item adopts its candidate per the fallback rule. Same shape as on plans / line items.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars across the line items under this hypothetical. NOT a rate."},"delta_vs_current":{"description":"Axis-by-axis difference vs current_totals. The headline 'should I do this' answer is delta_vs_current.monthly_net_savings.","$ref":"#/components/schemas/HypotheticalDelta"},"line_items":{"type":"array","description":"Per-line-item resolution for this hypothetical. Use to call out fallbacks ('14 of 20 line items would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current').","items":{"$ref":"#/components/schemas/HypotheticalLineItem"}}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","line_items","payment_option"],"additionalProperties":false},"HypotheticalDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the plan does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"HypotheticalLineItem":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"actual_term":{"description":"The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"actual_payment_option":{"description":"Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."}},"required":["actual_payment_option","actual_term","actual_term_reason","line_item_id"],"additionalProperties":false},"LineItemOfferComparisonRow":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"current":{"description":"The line item's current offer + lease, in the same shape as OfferComparisonEntrySchema. Its delta_vs_current is all zeros.","$ref":"#/components/schemas/OfferComparisonEntry"},"candidates":{"type":"array","description":"Alternative (offer, lease) pairs for this line item, filtered to the requested contract_terms and payment_options. Each entry carries its own contract_term and payment_option (on offer); fields offer_id, lease_menu_item_id, and selected_amount can be copied verbatim into POST /commitment-plans/{plan_id}/line-items/update (in the `updates` list) to swap the line item to that candidate.","items":{"$ref":"#/components/schemas/OfferComparisonEntry"}}},"required":["candidates","current","line_item_id"],"additionalProperties":false},"OfferComparisonEntry":{"type":"object","properties":{"is_current":{"type":"boolean","description":"True if this entry matches the line item's current offer + lease. Exactly one entry per response has this set; its `delta_vs_current` values are all zero."},"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","$ref":"#/components/schemas/CommitmentOffer"},"lease_menu_item_id":{"type":["string","null"],"format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`."},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":["number","null"],"description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost)."},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","$ref":"#/components/schemas/OfferComparisonDelta"}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","is_current","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5'), null for some commitment types"},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"product_description":{"type":["string","null"],"description":"Product description (e.g. 'Linux/UNIX')"},"display_name":{"type":["string","null"],"description":"Human-readable offer name"},"guaranteed_display_name":{"type":["string","null"],"description":"Offer name when purchased as an Archera Guaranteed Commitment"},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":["number","null"],"description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven."}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The LeaseMenuItem object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"LeaseMenuItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fee_type":{"type":"string"},"fee_rate":{"type":"number"},"is_rebate":{"type":"boolean"},"lockin_months":{"type":"integer"},"term_months":{"type":"integer"}},"required":["fee_rate","fee_type","is_rebate","lockin_months","term_months"],"additionalProperties":false}}}}
```

## The DailyUtilization object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"DailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date"},"reservation_utilization":{"type":"number"},"covered_cost":{"type":"number"},"cost":{"type":"number"},"potential_savings":{"type":["number","null"]},"running_hours":{"type":["number","null"]},"savings":{"type":"number"},"unutilized_commit":{"type":"number"},"gri_fees":{"type":"number"},"net_savings":{"type":"number"}},"required":["cost","covered_cost","date","gri_fees","net_savings","potential_savings","reservation_utilization","running_hours","savings","unutilized_commit"],"additionalProperties":false}}}}
```

## The PublicCommitment object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"PublicCommitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string"},"leased_display_name":{"type":"string"},"provider_reservation_id":{"type":"string"},"account_id":{"type":["string","null"]},"master_account_id":{"readOnly":true,"deprecated":true,"type":["string","null"]},"billing_account_id":{"type":["string","null"]},"type":{"type":"string"},"region":{"type":["string","null"]},"duration_seconds":{"type":["integer","null"]},"reservation_end":{"type":["string","null"]},"reservation_start":{"type":["string","null"]},"transfer_reservation_start":{"type":["string","null"],"format":"date-time"},"transfer_reservation_end":{"type":["string","null"],"format":"date-time"},"start_date":{"type":["string","null"],"format":"date-time"},"end_date":{"type":["string","null"],"format":"date-time"},"status":{"enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_leased":{"type":"boolean"},"is_active":{"type":"boolean"},"lease":{"anyOf":[{"$ref":"#/components/schemas/LeaseMenuItem"},{"type":"null"}]},"lease_start":{"type":["string","null"],"format":"date-time"},"lease_lockin_date":{"type":["string","null"],"format":"date-time"},"upfront_cost":{"type":"number"},"recurring_cost":{"type":"number"},"is_flexible":{"type":["boolean","null"]},"payment_option":{"enum":["No Upfront","Partial Upfront","All Upfront",null]},"offering_class":{"enum":["standard","convertible",null]},"offering_id":{"type":["string","null"]},"instance_count":{"type":["integer","null"]},"effective_instance_count":{"type":["integer","null"]},"product_description":{"type":["string","null"]},"instance_family":{"type":["string","null"]},"instance_type":{"type":["string","null"]},"tenancy":{"type":["string","null"]},"az":{"type":["string","null"]},"is_multi_az":{"type":["boolean","null"]},"plan_type":{"type":["string","null"]},"scope":{"enum":["shared","subscription","resource_group","management_group",null]},"name":{"type":["string","null"]},"order_id":{"type":["string","null"]},"resource_group":{"type":["string","null"]},"instance_flexibility":{"type":["boolean","null"]},"savings":{"type":["number","null"]},"monthly_savings":{"type":["number","null"]},"net_savings":{"type":["number","null"]},"utilization":{"type":["number","null"]},"potential_savings":{"type":["number","null"]},"running_hours":{"type":["number","null"]},"amortized_cost":{"type":["number","null"]},"daily_utilizations":{"type":"array","items":{"$ref":"#/components/schemas/DailyUtilization"}}},"required":["account_id","amortized_cost","az","billing_account_id","daily_utilizations","display_name","duration_seconds","effective_instance_count","end_date","id","instance_count","instance_family","instance_flexibility","instance_type","is_active","is_flexible","is_leased","is_multi_az","lease","lease_lockin_date","lease_start","leased_display_name","master_account_id","monthly_savings","name","net_savings","offering_class","offering_id","order_id","payment_option","plan_type","potential_savings","product_description","provider","provider_reservation_id","recurring_cost","region","reservation_end","reservation_start","resource_group","running_hours","savings","scope","start_date","status","tenancy","transfer_reservation_end","transfer_reservation_start","type","upfront_cost","utilization"],"additionalProperties":false},"LeaseMenuItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fee_type":{"type":"string"},"fee_rate":{"type":"number"},"is_rebate":{"type":"boolean"},"lockin_months":{"type":"integer"},"term_months":{"type":"integer"}},"required":["fee_rate","fee_type","is_rebate","lockin_months","term_months"],"additionalProperties":false},"DailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date"},"reservation_utilization":{"type":"number"},"covered_cost":{"type":"number"},"cost":{"type":"number"},"potential_savings":{"type":["number","null"]},"running_hours":{"type":["number","null"]},"savings":{"type":"number"},"unutilized_commit":{"type":"number"},"gri_fees":{"type":"number"},"net_savings":{"type":"number"}},"required":["cost","covered_cost","date","gri_fees","net_savings","potential_savings","reservation_utilization","running_hours","savings","unutilized_commit"],"additionalProperties":false}}}}
```

## The IdsResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"IdsResponse":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}}},"required":["ids"],"additionalProperties":false}}}}
```

## The DataPoint object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"DataPoint":{"type":"object","properties":{"date":{"type":"string"},"remaining_commit":{"type":"number"},"locked_commit":{"type":"number"},"unlocked_commit":{"type":"number"},"savings":{"type":"number"},"net_savings":{"type":"number"},"utilization":{"type":"number"},"unutilized_commit":{"type":"number"},"is_projection":{"type":"boolean","description":"Indicates whether this data point is a projection based on current commitment utilization patterns. Historical data (is_projection=false) reflects actual recorded metrics, while projected data (is_projection=true) represents estimated future values assuming commitments continue with their current utilization rates."}},"required":["date","is_projection","locked_commit","net_savings","remaining_commit","savings","unlocked_commit","unutilized_commit","utilization"],"additionalProperties":false}}}}
```

## The PubChartResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"PubChartResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DataPoint"}}},"additionalProperties":false},"DataPoint":{"type":"object","properties":{"date":{"type":"string"},"remaining_commit":{"type":"number"},"locked_commit":{"type":"number"},"unlocked_commit":{"type":"number"},"savings":{"type":"number"},"net_savings":{"type":"number"},"utilization":{"type":"number"},"unutilized_commit":{"type":"number"},"is_projection":{"type":"boolean","description":"Indicates whether this data point is a projection based on current commitment utilization patterns. Historical data (is_projection=false) reflects actual recorded metrics, while projected data (is_projection=true) represents estimated future values assuming commitments continue with their current utilization rates."}},"required":["date","is_projection","locked_commit","net_savings","remaining_commit","savings","unlocked_commit","unutilized_commit","utilization"],"additionalProperties":false}}}}
```

## The ExchangePurchase object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ExchangePurchase":{"type":"object","properties":{"account_id":{"type":["string","null"],"description":"Target cloud account/subscription for the purchase."},"contract_term":{"description":"User-facing purchase commitment term. For leased/guaranteed purchases this is the lease lock-in term; for native purchases it is the offer duration.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"lease_menu_item_id":{"type":["string","null"],"format":"uuid","description":"Lease menu item attached to the purchase side, or null for native purchases."},"quantity":{"type":"integer","description":"Quantity of the Azure reservation to purchase."},"offer":{"description":"Azure reservation offer being purchased.","$ref":"#/components/schemas/CommitmentOffer"},"commitment_upfront_cost":{"type":"number","description":"One-time upfront dollars required at signing for the purchase side. NOT a monthly rate."},"commitment_financials_monthly_rate":{"description":"Purchase-side plan line item economics as 730-hour monthly rates.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","offer","quantity"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5'), null for some commitment types"},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"product_description":{"type":["string","null"],"description":"Product description (e.g. 'Linux/UNIX')"},"display_name":{"type":["string","null"],"description":"Human-readable offer name"},"guaranteed_display_name":{"type":["string","null"],"description":"Offer name when purchased as an Archera Guaranteed Commitment"},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The Commitment object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":["string","null"],"description":"Cloud account ID this commitment is in"},"billing_account_id":{"type":["string","null"],"description":"Billing/management account ID"},"start_date":{"type":["string","null"],"format":"date-time","description":"When the commitment started"},"end_date":{"type":["string","null"],"format":"date-time","description":"When the commitment expires"},"duration_seconds":{"type":["integer","null"],"description":"Total commitment duration in seconds"},"guarantee_start":{"type":["string","null"],"format":"date-time","description":"When the Archera guarantee period started"},"guarantee_lockin_date":{"type":["string","null"],"format":"date-time","description":"When the Archera guarantee lock-in period ends"},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge')"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5')"},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"},"instance_count":{"type":["integer","null"],"description":"Number of instances covered"},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]}},"required":["id","provider"],"additionalProperties":false}}}}
```

## The ExchangeReturn object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ExchangeReturn":{"type":"object","properties":{"commitment":{"description":"Azure commitment proposed to return in the exchange.","$ref":"#/components/schemas/Commitment"},"quantity":{"type":"integer","description":"Quantity of this commitment proposed for return."},"remaining_lifetime_commitment":{"type":"number","description":"Remaining Azure commitment value returned for this commitment quantity. This is lifetime exchange value, not a monthly rate."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitment over the DailyUtilization period (0-1)."},"underutilized_commitment_cost":{"type":"number","description":"Estimated underutilized commitment cost over the DailyUtilization period. This is a period total, not a monthly rate."},"utilization_days":{"type":"integer","description":"Number of DailyUtilization days behind the utilization fields."},"reservation_resource_id":{"type":"string","description":"Azure reservation resource ID required by Azure exchange APIs."},"commitment_financials_monthly_rate":{"description":"Returned commitment economics as a 730-hour monthly rate for the selected integer return quantity. Cost comes from DailyUtilization commitment cost for the response period, scaled to the returned quantity. Savings are computed after assigning as much utilization as possible to the quantity that remains committed, so returned fully-utilized quantities can have positive savings and underutilized quantities have negative savings. Archera premium and rebate are excluded from exchange recommendations and are not included in net savings.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}},"required":["commitment","commitment_financials_monthly_rate","quantity","remaining_lifetime_commitment","reservation_resource_id","underutilized_commitment_cost","utilization","utilization_days"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":["string","null"],"description":"Cloud account ID this commitment is in"},"billing_account_id":{"type":["string","null"],"description":"Billing/management account ID"},"start_date":{"type":["string","null"],"format":"date-time","description":"When the commitment started"},"end_date":{"type":["string","null"],"format":"date-time","description":"When the commitment expires"},"duration_seconds":{"type":["integer","null"],"description":"Total commitment duration in seconds"},"guarantee_start":{"type":["string","null"],"format":"date-time","description":"When the Archera guarantee period started"},"guarantee_lockin_date":{"type":["string","null"],"format":"date-time","description":"When the Archera guarantee lock-in period ends"},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge')"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5')"},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"},"instance_count":{"type":["integer","null"],"description":"Number of instances covered"},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The ExchangeReturnedCommitmentDailyUtilization object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ExchangeReturnedCommitmentDailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"DailyUtilization date."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitments for this date (0-1), dollar weighted by each return's commitment cost."}},"required":["date","utilization"],"additionalProperties":false}}}}
```

## The ExchangeRecommendationDelta object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ExchangeRecommendationDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Purchase monthly net savings minus returned commitments' monthly net savings. Positive means the exchange purchase saves more per 730-hour month."},"monthly_commitment_cost":{"type":"number","description":"Purchase monthly commitment cost minus returned commitments' monthly commitment cost. Positive means more monthly commitment spend."},"purchase_upfront_cost":{"type":"number","description":"Purchase-side one-time upfront cost only. Not netted against returned commitments because returned financials are monthly-rate utilization actuals and have no upfront component. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","purchase_upfront_cost"],"additionalProperties":false}}}}
```

## The ExchangeRecommendation object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ExchangeRecommendation":{"type":"object","properties":{"purchase_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value of the purchase side."},"returned_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value returned by the exchange."},"additional_lifetime_commitment":{"type":"number","description":"Purchase lifetime commitment minus returned lifetime commitment. Azure exchange policy requires this to be non-negative."},"purchase":{"$ref":"#/components/schemas/ExchangePurchase"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeReturn"}},"purchase_commitment_financials_monthly_rate":{"description":"Purchase-side monthly-rate financials.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"returned_commitment_financials_monthly_rate":{"description":"Returned commitments' rolled-up monthly-rate financials for the selected integer return quantities. Cost comes from DailyUtilization commitment cost, and savings are computed after assigning as much utilization as possible to the quantity that remains committed. Rebate and Archera premium are excluded from exchange recommendations and are not included in net savings.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"returned_commitment_daily_utilizations":{"type":"array","description":"Daily whole-commitment utilization for the returned commitments, dollar weighted by each return's commitment cost. Use this for exchange-level utilization charts.","items":{"$ref":"#/components/schemas/ExchangeReturnedCommitmentDailyUtilization"}},"reason":{"type":["string","null"],"description":"Short human-readable reason this exchange was recommended, based on how the exchanger generated it."},"delta_vs_returned":{"description":"Purchase-side economics compared with returned-commitment economics. Monthly fields are purchase-side minus returned-side; purchase_upfront_cost is purchase-side one-time upfront only and is not netted. Purchase financials come from plan-amortized line item financials; returned financials come from DailyUtilization cost and covered usage for the selected integer return quantities, normalized to 730-hour monthly rates.","$ref":"#/components/schemas/ExchangeRecommendationDelta"}},"required":["additional_lifetime_commitment","delta_vs_returned","purchase","purchase_commitment_financials_monthly_rate","purchase_lifetime_commitment","returned_commitment_daily_utilizations","returned_commitment_financials_monthly_rate","returned_lifetime_commitment","returns"],"additionalProperties":false},"ExchangePurchase":{"type":"object","properties":{"account_id":{"type":["string","null"],"description":"Target cloud account/subscription for the purchase."},"contract_term":{"description":"User-facing purchase commitment term. For leased/guaranteed purchases this is the lease lock-in term; for native purchases it is the offer duration.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"lease_menu_item_id":{"type":["string","null"],"format":"uuid","description":"Lease menu item attached to the purchase side, or null for native purchases."},"quantity":{"type":"integer","description":"Quantity of the Azure reservation to purchase."},"offer":{"description":"Azure reservation offer being purchased.","$ref":"#/components/schemas/CommitmentOffer"},"commitment_upfront_cost":{"type":"number","description":"One-time upfront dollars required at signing for the purchase side. NOT a monthly rate."},"commitment_financials_monthly_rate":{"description":"Purchase-side plan line item economics as 730-hour monthly rates.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","offer","quantity"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5'), null for some commitment types"},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"product_description":{"type":["string","null"],"description":"Product description (e.g. 'Linux/UNIX')"},"display_name":{"type":["string","null"],"description":"Human-readable offer name"},"guaranteed_display_name":{"type":["string","null"],"description":"Offer name when purchased as an Archera Guaranteed Commitment"},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"ExchangeReturn":{"type":"object","properties":{"commitment":{"description":"Azure commitment proposed to return in the exchange.","$ref":"#/components/schemas/Commitment"},"quantity":{"type":"integer","description":"Quantity of this commitment proposed for return."},"remaining_lifetime_commitment":{"type":"number","description":"Remaining Azure commitment value returned for this commitment quantity. This is lifetime exchange value, not a monthly rate."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitment over the DailyUtilization period (0-1)."},"underutilized_commitment_cost":{"type":"number","description":"Estimated underutilized commitment cost over the DailyUtilization period. This is a period total, not a monthly rate."},"utilization_days":{"type":"integer","description":"Number of DailyUtilization days behind the utilization fields."},"reservation_resource_id":{"type":"string","description":"Azure reservation resource ID required by Azure exchange APIs."},"commitment_financials_monthly_rate":{"description":"Returned commitment economics as a 730-hour monthly rate for the selected integer return quantity. Cost comes from DailyUtilization commitment cost for the response period, scaled to the returned quantity. Savings are computed after assigning as much utilization as possible to the quantity that remains committed, so returned fully-utilized quantities can have positive savings and underutilized quantities have negative savings. Archera premium and rebate are excluded from exchange recommendations and are not included in net savings.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}},"required":["commitment","commitment_financials_monthly_rate","quantity","remaining_lifetime_commitment","reservation_resource_id","underutilized_commitment_cost","utilization","utilization_days"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":["string","null"],"description":"Cloud account ID this commitment is in"},"billing_account_id":{"type":["string","null"],"description":"Billing/management account ID"},"start_date":{"type":["string","null"],"format":"date-time","description":"When the commitment started"},"end_date":{"type":["string","null"],"format":"date-time","description":"When the commitment expires"},"duration_seconds":{"type":["integer","null"],"description":"Total commitment duration in seconds"},"guarantee_start":{"type":["string","null"],"format":"date-time","description":"When the Archera guarantee period started"},"guarantee_lockin_date":{"type":["string","null"],"format":"date-time","description":"When the Archera guarantee lock-in period ends"},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge')"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5')"},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"},"instance_count":{"type":["integer","null"],"description":"Number of instances covered"},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]}},"required":["id","provider"],"additionalProperties":false},"ExchangeReturnedCommitmentDailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"DailyUtilization date."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitments for this date (0-1), dollar weighted by each return's commitment cost."}},"required":["date","utilization"],"additionalProperties":false},"ExchangeRecommendationDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Purchase monthly net savings minus returned commitments' monthly net savings. Positive means the exchange purchase saves more per 730-hour month."},"monthly_commitment_cost":{"type":"number","description":"Purchase monthly commitment cost minus returned commitments' monthly commitment cost. Positive means more monthly commitment spend."},"purchase_upfront_cost":{"type":"number","description":"Purchase-side one-time upfront cost only. Not netted against returned commitments because returned financials are monthly-rate utilization actuals and have no upfront component. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","purchase_upfront_cost"],"additionalProperties":false}}}}
```

## The ExchangeRecommendationsResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ExchangeRecommendationsResponse":{"type":"object","properties":{"current_utilization_lookback_days":{"type":"integer","description":"Number of trailing days of DailyUtilization used for returned-commitment utilization and financials."},"data":{"type":"array","description":"Azure exchange recommendations.","items":{"$ref":"#/components/schemas/ExchangeRecommendation"}}},"required":["current_utilization_lookback_days","data"],"additionalProperties":false},"ExchangeRecommendation":{"type":"object","properties":{"purchase_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value of the purchase side."},"returned_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value returned by the exchange."},"additional_lifetime_commitment":{"type":"number","description":"Purchase lifetime commitment minus returned lifetime commitment. Azure exchange policy requires this to be non-negative."},"purchase":{"$ref":"#/components/schemas/ExchangePurchase"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeReturn"}},"purchase_commitment_financials_monthly_rate":{"description":"Purchase-side monthly-rate financials.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"returned_commitment_financials_monthly_rate":{"description":"Returned commitments' rolled-up monthly-rate financials for the selected integer return quantities. Cost comes from DailyUtilization commitment cost, and savings are computed after assigning as much utilization as possible to the quantity that remains committed. Rebate and Archera premium are excluded from exchange recommendations and are not included in net savings.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"returned_commitment_daily_utilizations":{"type":"array","description":"Daily whole-commitment utilization for the returned commitments, dollar weighted by each return's commitment cost. Use this for exchange-level utilization charts.","items":{"$ref":"#/components/schemas/ExchangeReturnedCommitmentDailyUtilization"}},"reason":{"type":["string","null"],"description":"Short human-readable reason this exchange was recommended, based on how the exchanger generated it."},"delta_vs_returned":{"description":"Purchase-side economics compared with returned-commitment economics. Monthly fields are purchase-side minus returned-side; purchase_upfront_cost is purchase-side one-time upfront only and is not netted. Purchase financials come from plan-amortized line item financials; returned financials come from DailyUtilization cost and covered usage for the selected integer return quantities, normalized to 730-hour monthly rates.","$ref":"#/components/schemas/ExchangeRecommendationDelta"}},"required":["additional_lifetime_commitment","delta_vs_returned","purchase","purchase_commitment_financials_monthly_rate","purchase_lifetime_commitment","returned_commitment_daily_utilizations","returned_commitment_financials_monthly_rate","returned_lifetime_commitment","returns"],"additionalProperties":false},"ExchangePurchase":{"type":"object","properties":{"account_id":{"type":["string","null"],"description":"Target cloud account/subscription for the purchase."},"contract_term":{"description":"User-facing purchase commitment term. For leased/guaranteed purchases this is the lease lock-in term; for native purchases it is the offer duration.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"lease_menu_item_id":{"type":["string","null"],"format":"uuid","description":"Lease menu item attached to the purchase side, or null for native purchases."},"quantity":{"type":"integer","description":"Quantity of the Azure reservation to purchase."},"offer":{"description":"Azure reservation offer being purchased.","$ref":"#/components/schemas/CommitmentOffer"},"commitment_upfront_cost":{"type":"number","description":"One-time upfront dollars required at signing for the purchase side. NOT a monthly rate."},"commitment_financials_monthly_rate":{"description":"Purchase-side plan line item economics as 730-hour monthly rates.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","offer","quantity"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5'), null for some commitment types"},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"product_description":{"type":["string","null"],"description":"Product description (e.g. 'Linux/UNIX')"},"display_name":{"type":["string","null"],"description":"Human-readable offer name"},"guaranteed_display_name":{"type":["string","null"],"description":"Offer name when purchased as an Archera Guaranteed Commitment"},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","$ref":"#/components/schemas/CloudProviderCostBreakdown"}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"ExchangeReturn":{"type":"object","properties":{"commitment":{"description":"Azure commitment proposed to return in the exchange.","$ref":"#/components/schemas/Commitment"},"quantity":{"type":"integer","description":"Quantity of this commitment proposed for return."},"remaining_lifetime_commitment":{"type":"number","description":"Remaining Azure commitment value returned for this commitment quantity. This is lifetime exchange value, not a monthly rate."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitment over the DailyUtilization period (0-1)."},"underutilized_commitment_cost":{"type":"number","description":"Estimated underutilized commitment cost over the DailyUtilization period. This is a period total, not a monthly rate."},"utilization_days":{"type":"integer","description":"Number of DailyUtilization days behind the utilization fields."},"reservation_resource_id":{"type":"string","description":"Azure reservation resource ID required by Azure exchange APIs."},"commitment_financials_monthly_rate":{"description":"Returned commitment economics as a 730-hour monthly rate for the selected integer return quantity. Cost comes from DailyUtilization commitment cost for the response period, scaled to the returned quantity. Savings are computed after assigning as much utilization as possible to the quantity that remains committed, so returned fully-utilized quantities can have positive savings and underutilized quantities have negative savings. Archera premium and rebate are excluded from exchange recommendations and are not included in net savings.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}},"required":["commitment","commitment_financials_monthly_rate","quantity","remaining_lifetime_commitment","reservation_resource_id","underutilized_commitment_cost","utilization","utilization_days"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":["string","null"],"description":"Cloud account ID this commitment is in"},"billing_account_id":{"type":["string","null"],"description":"Billing/management account ID"},"start_date":{"type":["string","null"],"format":"date-time","description":"When the commitment started"},"end_date":{"type":["string","null"],"format":"date-time","description":"When the commitment expires"},"duration_seconds":{"type":["integer","null"],"description":"Total commitment duration in seconds"},"guarantee_start":{"type":["string","null"],"format":"date-time","description":"When the Archera guarantee period started"},"guarantee_lockin_date":{"type":["string","null"],"format":"date-time","description":"When the Archera guarantee lock-in period ends"},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge')"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5')"},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"},"instance_count":{"type":["integer","null"],"description":"Number of instances covered"},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]}},"required":["id","provider"],"additionalProperties":false},"ExchangeReturnedCommitmentDailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"DailyUtilization date."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitments for this date (0-1), dollar weighted by each return's commitment cost."}},"required":["date","utilization"],"additionalProperties":false},"ExchangeRecommendationDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Purchase monthly net savings minus returned commitments' monthly net savings. Positive means the exchange purchase saves more per 730-hour month."},"monthly_commitment_cost":{"type":"number","description":"Purchase monthly commitment cost minus returned commitments' monthly commitment cost. Positive means more monthly commitment spend."},"purchase_upfront_cost":{"type":"number","description":"Purchase-side one-time upfront cost only. Not netted against returned commitments because returned financials are monthly-rate utilization actuals and have no upfront component. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","purchase_upfront_cost"],"additionalProperties":false}}}}
```

## The ApplyExchangePurchase object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ApplyExchangePurchase":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Azure reservation offer ID to purchase."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this offer to purchase."}},"required":["offer_id","quantity"],"additionalProperties":false}}}}
```

## The ApplyExchangeReturn object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ApplyExchangeReturn":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Existing Azure commitment ID to return."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this commitment to return."}},"required":["commitment_id","quantity"],"additionalProperties":false}}}}
```

## The ApplyExchangeRecommendationsArgs object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ApplyExchangeRecommendationsArgs":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"purchases":{"type":"array","minItems":1,"description":"Explicit purchase-side line items for one exchange recommendation.","items":{"$ref":"#/components/schemas/ApplyExchangePurchase"}},"returns":{"type":"array","minItems":1,"description":"Explicit return-side line items for one exchange recommendation.","items":{"$ref":"#/components/schemas/ApplyExchangeReturn"}}},"required":["provider","purchases","returns"],"additionalProperties":false},"ApplyExchangePurchase":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Azure reservation offer ID to purchase."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this offer to purchase."}},"required":["offer_id","quantity"],"additionalProperties":false},"ApplyExchangeReturn":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Existing Azure commitment ID to return."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this commitment to return."}},"required":["commitment_id","quantity"],"additionalProperties":false}}}}
```

## The ApplyExchangeRecommendationsResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ApplyExchangeRecommendationsResponse":{"type":"object","properties":{"status":{"type":"string","description":"Application status for the exchange recommendations."},"recommendation_count":{"type":"integer","description":"Number of exchange recommendations applied."}},"required":["recommendation_count","status"],"additionalProperties":false}}}}
```

## The PublicMetrics object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"PublicMetrics":{"type":"object","properties":{"lifetime_savings":{"type":"number"},"lifetime_gri_savings":{"type":"number"},"mtd_savings":{"type":"number"},"mtd_gri_savings":{"type":"number"},"purchase_automation_enabled":{"type":"boolean"},"buyback_automation_enabled":{"type":"boolean"},"has_actioned_plan":{"type":"boolean"},"has_pending_actions":{"type":"boolean"},"latest_execution_date":{"type":"string","format":"date"},"purchase_missed_savings":{"type":"number"},"buyback_missed_savings":{"type":"number"},"total_daily_missed_savings":{"type":"number"},"hourly_missed_savings":{"type":"number"},"missed_savings_start_date":{"type":"string","format":"date"},"missed_savings_end_date":{"type":"string","format":"date"},"expiring_savings":{"type":"number"},"coverage":{"type":"number"},"utilization":{"type":"number"}},"required":["buyback_automation_enabled","buyback_missed_savings","coverage","expiring_savings","has_actioned_plan","has_pending_actions","hourly_missed_savings","latest_execution_date","lifetime_gri_savings","lifetime_savings","missed_savings_end_date","missed_savings_start_date","mtd_gri_savings","mtd_savings","purchase_automation_enabled","purchase_missed_savings","total_daily_missed_savings","utilization"],"additionalProperties":false}}}}
```

## The Org object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"Org":{"type":"object","properties":{"org_id":{"type":"string","pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z","description":"Unique organization identifier"},"name":{"type":"string","description":"Organization name"},"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"],"description":"User's role in the organization (e.g., admin, user, support, cloud_rep, restricted_user)"},"kind":{"description":"Type of membership: 'direct' (direct member), 'partnership' (via partner org), 'staff' (Archera staff)","enum":["direct","staff","partnership"]}},"required":["kind","name","org_id","role"],"additionalProperties":false}}}}
```

## The SKUUsageDaily object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"SKUUsageDaily":{"type":"object","properties":{"date":{"type":"string","format":"date"},"usage_account_id":{"readOnly":true,"deprecated":true,"type":"string"},"sub_account_id":{"type":"string"},"usage":{"type":"number"},"reservation_usage":{"type":"number"},"free_tier_usage":{"type":"number"},"ondemand_cost":{"type":"number"},"reserved_cost":{"type":"number"},"if_all_ondemand_cost":{"type":"number"},"spot_cost":{"type":"number"},"free_tier_savings":{"type":"number"},"usage_type":{"type":["string","null"]},"common_usage_type":{"type":["string","null"]},"covered_usage":{"type":"number"},"uptime":{"type":"number"}},"required":["common_usage_type","covered_usage","date","free_tier_savings","free_tier_usage","if_all_ondemand_cost","ondemand_cost","reservation_usage","reserved_cost","spot_cost","sub_account_id","uptime","usage","usage_account_id","usage_type"],"additionalProperties":false}}}}
```

## The SavingsEstimateRequest object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"SavingsEstimateRequest":{"type":"object","properties":{"upload_id":{"type":"string","format":"uuid"}},"required":["upload_id"],"additionalProperties":false}}}}
```

## The ValueRange object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"ValueRange":{"type":"object","properties":{"estimate":{"type":"number"},"lower_bound":{"type":["number","null"]},"upper_bound":{"type":["number","null"]}},"required":["estimate","lower_bound","upper_bound"],"additionalProperties":false}}}}
```

## The CostLineItem object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CostLineItem":{"type":"object","properties":{"service":{"type":"string"},"reservable_service":{"type":["string","null"]},"resource_type":{"type":["string","null"]},"usage_quantity":{"anyOf":[{"$ref":"#/components/schemas/ValueRange"},{"type":"null"}]},"usage_unit":{"type":["string","null"]},"cost":{"$ref":"#/components/schemas/ValueRange"},"region":{"type":["string","null"]},"spend_type":{"enum":["on_demand","reserved","unreservable","unknown"]},"savings_estimate":{"anyOf":[{"$ref":"#/components/schemas/ValueRange"},{"type":"null"}]}},"required":["cost","region","reservable_service","resource_type","savings_estimate","service","spend_type","usage_quantity","usage_unit"],"additionalProperties":false},"ValueRange":{"type":"object","properties":{"estimate":{"type":"number"},"lower_bound":{"type":["number","null"]},"upper_bound":{"type":["number","null"]}},"required":["estimate","lower_bound","upper_bound"],"additionalProperties":false}}}}
```

## The SavingsEstimate object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"SavingsEstimate":{"type":"object","properties":{"provider":{"type":["string","null"],"enum":["aws","azure","gcp",null]},"source_format":{"type":"string"},"period_start":{"type":["string","null"],"format":"date"},"period_end":{"type":["string","null"],"format":"date"},"account_id":{"type":["string","null"]},"currency":{"type":"string"},"is_projected":{"type":"boolean"},"extraction_status":{"enum":["complete","partial","unverified"]},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/CostLineItem"}},"total_cost":{"readOnly":true,"$ref":"#/components/schemas/ValueRange"},"total_savings_estimate":{"readOnly":true,"$ref":"#/components/schemas/ValueRange"}},"required":["account_id","currency","extraction_status","is_projected","line_items","period_end","period_start","provider","source_format","total_cost","total_savings_estimate"],"additionalProperties":false},"CostLineItem":{"type":"object","properties":{"service":{"type":"string"},"reservable_service":{"type":["string","null"]},"resource_type":{"type":["string","null"]},"usage_quantity":{"anyOf":[{"$ref":"#/components/schemas/ValueRange"},{"type":"null"}]},"usage_unit":{"type":["string","null"]},"cost":{"$ref":"#/components/schemas/ValueRange"},"region":{"type":["string","null"]},"spend_type":{"enum":["on_demand","reserved","unreservable","unknown"]},"savings_estimate":{"anyOf":[{"$ref":"#/components/schemas/ValueRange"},{"type":"null"}]}},"required":["cost","region","reservable_service","resource_type","savings_estimate","service","spend_type","usage_quantity","usage_unit"],"additionalProperties":false},"ValueRange":{"type":"object","properties":{"estimate":{"type":"number"},"lower_bound":{"type":["number","null"]},"upper_bound":{"type":["number","null"]}},"required":["estimate","lower_bound","upper_bound"],"additionalProperties":false}}}}
```

## The CreatePublicUpload object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"CreatePublicUpload":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255,"description":"Optional partner-supplied context for the uploaded billing file"},"file":{"writeOnly":true,"description":"Billing PDF, CSV, JSON, or text file to upload for a savings estimate","type":"string","format":"binary"}},"required":["file"],"additionalProperties":false}}}}
```

## The PublicUpload object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"PublicUpload":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"org_id":{"type":"string","readOnly":true,"maxLength":50},"file_name":{"type":"string","readOnly":true,"maxLength":255},"content_type":{"type":"string","readOnly":true,"maxLength":255},"size_bytes":{"type":"integer","readOnly":true},"description":{"type":["string","null"],"readOnly":true,"maxLength":255},"upload_status":{"readOnly":true,"type":"string","enum":["PENDING","PROCESSING","COMPLETE","ERROR"]},"source":{"readOnly":true,"enum":["agent_upload","attachment","partner_api"]},"detected_type":{"type":["string","null"],"readOnly":true,"maxLength":64},"available_actions":{"type":"array","readOnly":true,"items":{"enum":["savings_estimate"]}}},"required":["content_type","created_at","description","detected_type","file_name","id","org_id","size_bytes","source","upload_status"],"additionalProperties":false}}}}
```

## The JWK object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"JWK":{"type":"object","properties":{"kty":{"type":"string","description":"Key type (e.g., 'RSA')"},"use":{"type":"string","description":"Public key use (e.g., 'sig' for signature)"},"kid":{"type":"string","description":"Key ID for identifying the key"},"alg":{"type":"string","description":"Algorithm (e.g., 'RS256')"},"n":{"type":"string","description":"RSA modulus (base64url encoded)"},"e":{"type":"string","description":"RSA public exponent (base64url encoded)"}},"required":["alg","e","kid","kty","n","use"],"additionalProperties":false}}}}
```

## The JWKS object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"JWKS":{"type":"object","properties":{"keys":{"type":"array","description":"Array of JSON Web Keys","items":{"$ref":"#/components/schemas/JWK"}}},"required":["keys"],"additionalProperties":false},"JWK":{"type":"object","properties":{"kty":{"type":"string","description":"Key type (e.g., 'RSA')"},"use":{"type":"string","description":"Public key use (e.g., 'sig' for signature)"},"kid":{"type":"string","description":"Key ID for identifying the key"},"alg":{"type":"string","description":"Algorithm (e.g., 'RS256')"},"n":{"type":"string","description":"RSA modulus (base64url encoded)"},"e":{"type":"string","description":"RSA public exponent (base64url encoded)"}},"required":["alg","e","kid","kty","n","use"],"additionalProperties":false}}}}
```

## The OAuthMetadata object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"OAuthMetadata":{"type":"object","properties":{"issuer":{"type":"string","description":"The authorization server's issuer identifier URL"},"authorization_endpoint":{"type":"string","description":"URL of the OAuth 2.0 authorization endpoint"},"token_endpoint":{"type":"string","description":"URL of the OAuth 2.0 token endpoint"},"revocation_endpoint":{"type":"string","description":"URL of the OAuth 2.0 token revocation endpoint (RFC 7009)"},"registration_endpoint":{"type":"string","description":"URL of the OAuth 2.0 dynamic client registration endpoint (RFC 7591)"},"jwks_uri":{"type":"string","description":"URL of the JSON Web Key Set document"},"response_types_supported":{"type":"array","description":"OAuth 2.0 response_type values supported","items":{"type":"string"}},"grant_types_supported":{"type":"array","description":"OAuth 2.0 grant type values supported","items":{"type":"string"}},"code_challenge_methods_supported":{"type":"array","description":"PKCE code challenge methods supported","items":{"type":"string"}},"token_endpoint_auth_methods_supported":{"type":"array","description":"Client authentication methods supported at token endpoint","items":{"type":"string"}},"scopes_supported":{"type":"array","description":"OAuth 2.0 scope values supported","items":{"type":"string"}},"service_documentation":{"type":"string","description":"URL of service documentation for developers"}},"required":["authorization_endpoint","code_challenge_methods_supported","grant_types_supported","issuer","jwks_uri","registration_endpoint","response_types_supported","revocation_endpoint","scopes_supported","token_endpoint","token_endpoint_auth_methods_supported"],"additionalProperties":false}}}}
```

## The OAuthSessionResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"OAuthSessionResponse":{"type":"object","properties":{"token_id":{"type":"string","pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"client_name":{"type":"string"},"client_id":{"type":"string"},"created_at":{"type":"integer"},"scope":{"type":"string"}},"required":["client_id","client_name","created_at","scope","token_id"],"additionalProperties":false}}}}
```

## The RevokeAllSessionsResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"components":{"schemas":{"RevokeAllSessionsResponse":{"type":"object","properties":{"message":{"type":"string"},"count":{"type":"integer"}},"required":["count","message"],"additionalProperties":false}}}}
```


# Partner API

The Archera Partner API enables MSPs, resellers, and cloud consultants to deliver white-label cost optimization at scale. Programmatically onboard customers, access AI-powered commitment recommendations for each account, and execute cloud commitment purchases (RIs, Savings Plans, Azure Reservations) without touching cloud consoles.

Built for multi-tenant management, the Partner API lets you automate the entire optimization workflow—from customer onboarding through AWS/Azure integration to one-click commitment purchasing. Deliver enterprise-grade savings as a native feature of your platform and create new revenue streams while keeping customers in your ecosystem.


# Organizations

API for managing child organizations of a channel partner

## /orgs

> Registers a new child organization under the channel partner. Creates the organization, sets up user memberships, and establishes the partnership relationship.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"Organizations","description":"API for managing child organizations of a channel partner"}],"paths":{"/v2/partners/{partner_org_id}/orgs":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterOrgResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterOrg"}}}},"tags":["Organizations"],"summary":"/orgs","description":"Registers a new child organization under the channel partner. Creates the organization, sets up user memberships, and establishes the partnership relationship."}}},"components":{"schemas":{"RegisterOrgResponse":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"memberships":{"readOnly":true,"type":"array","items":{"$ref":"#/components/schemas/OrgMembershipResponse"}},"domain":{"type":["string","null"],"readOnly":true},"primary_address":{"readOnly":true,"anyOf":[{"$ref":"#/components/schemas/MutateAddress"},{"type":"null"}]},"aws_marketplace_offer_link":{"type":["string","null"],"format":"url","readOnly":true},"azure_marketplace_offer_link":{"type":["string","null"],"format":"url","readOnly":true},"gcp_marketplace_offer_link":{"type":["string","null"],"format":"url","readOnly":true}},"required":["id","name"],"additionalProperties":false},"OrgMembershipResponse":{"type":"object","properties":{"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"],"readOnly":true},"username":{"type":"string","format":"email","readOnly":true,"maxLength":255}},"additionalProperties":false},"MutateAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":["string","null"],"default":null},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"}},"required":["city","country","line1","state","zip"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"RegisterOrg":{"type":"object","properties":{"name":{"type":"string"},"labra_subscription_id":{"type":"string"},"users":{"type":"array","items":{"$ref":"#/components/schemas/UserInvite"}},"domain":{"type":["string","null"]},"primary_address":{"anyOf":[{"$ref":"#/components/schemas/MutateAddress"},{"type":"null"}]},"aws_marketplace_offer_link":{"type":["string","null"],"format":"url"},"azure_marketplace_offer_link":{"type":["string","null"],"format":"url"},"gcp_marketplace_offer_link":{"type":["string","null"],"format":"url"}},"required":["name"],"additionalProperties":false},"UserInvite":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":255},"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"]}},"required":["email"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /orgs/{child\_org\_id}/invites

> Invites users to the channel partner organization. Sends email invitations to the specified user emails with roles of user, admin, support, cloud\_rep, restricted\_user.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"Organizations","description":"API for managing child organizations of a channel partner"}],"paths":{"/v2/partners/{partner_org_id}/orgs/{child_org_id}/invites":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrgMembershipResponse"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteUsers"}}}},"tags":["Organizations"],"summary":"/orgs/{child_org_id}/invites","description":"Invites users to the channel partner organization. Sends email invitations to the specified user emails with roles of user, admin, support, cloud_rep, restricted_user."}}},"components":{"schemas":{"OrgMembershipResponse":{"type":"object","properties":{"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"],"readOnly":true},"username":{"type":"string","format":"email","readOnly":true,"maxLength":255}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"InviteUsers":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/UserInvite"}}},"required":["users"],"additionalProperties":false},"UserInvite":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":255},"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"]}},"required":["email"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Partners

partners api automation

## /cloudformation\_template

> Generates CloudFormation template for AWS integration. Creates the necessary IAM role and policy template for setting up AWS access.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"partners","description":"partners api automation"}],"paths":{"/v2/org/{org_id}/partners/onboarding/aws/cloudformation_template":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloudFormation"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["partners"],"summary":"/cloudformation_template","description":"Generates CloudFormation template for AWS integration. Creates the necessary IAM role and policy template for setting up AWS access."}}},"components":{"schemas":{"CloudFormation":{"type":"object","properties":{"template":{"type":"object","additionalProperties":{}}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /launch-stack-url

> Generates AWS CloudFormation launch stack URL. Creates a pre-configured URL to deploy the CloudFormation stack in the AWS console.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"partners","description":"partners api automation"}],"paths":{"/v2/org/{org_id}/partners/onboarding/aws/launch-stack-url":{"get":{"parameters":[{"in":"query","name":"read_only","schema":{"type":"boolean","default":false},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchStackUrls"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["partners"],"summary":"/launch-stack-url","description":"Generates AWS CloudFormation launch stack URL. Creates a pre-configured URL to deploy the CloudFormation stack in the AWS console."}}},"components":{"schemas":{"LaunchStackUrls":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /verify

> Runs AWS onboarding verification process. Creates a new CUR or uses an existing CUR and verifies AWS integration setup and returns validation status for all required features.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"partners","description":"partners api automation"}],"paths":{"/v2/org/{org_id}/partners/onboarding/aws/verify":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Validation"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationArgs"}}}},"tags":["partners"],"summary":"/verify","description":"Runs AWS onboarding verification process. Creates a new CUR or uses an existing CUR and verifies AWS integration setup and returns validation status for all required features."}}},"components":{"schemas":{"Validation":{"type":"object","properties":{"feature":{"type":"string"},"status":{"type":"string","enum":["available","warning","missing","unknown"]}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"VerificationArgs":{"type":"object","properties":{"onboarding_id":{"type":"string","pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"account_id":{"type":"string"},"read_only":{"type":"boolean","default":false},"existing_cur":{"$ref":"#/components/schemas/ExistingCUR"}},"additionalProperties":false},"ExistingCUR":{"type":"object","properties":{"region":{"type":"string"},"bucket":{"type":"string"},"prefix":{"type":"string"},"report_name":{"type":"string"}},"required":["bucket","prefix","region","report_name"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /auth-url

> Generates Azure authentication URL for onboarding. Creates or updates Azure onboarding record with tenant and subscription details, then returns the auth URL.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"partners","description":"partners api automation"}],"paths":{"/v2/org/{org_id}/partners/onboarding/azure/auth-url":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AzureAuthUrlResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AzureAuthUrlArgs"}}}},"tags":["partners"],"summary":"/auth-url","description":"Generates Azure authentication URL for onboarding. Creates or updates Azure onboarding record with tenant and subscription details, then returns the auth URL."}}},"components":{"schemas":{"AzureAuthUrlResponse":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"AzureAuthUrlArgs":{"type":"object","properties":{"azure_tenant_id":{"type":"string"},"azure_subscription_id":{"type":"string"}},"required":["azure_subscription_id","azure_tenant_id"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /verify

> Runs Azure onboarding verification process. Executes the complete onboarding workflow and returns validation results for all features.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"partners","description":"partners api automation"}],"paths":{"/v2/org/{org_id}/partners/onboarding/azure/verify":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Validation"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["partners"],"summary":"/verify","description":"Runs Azure onboarding verification process. Executes the complete onboarding workflow and returns validation results for all features."}}},"components":{"schemas":{"Validation":{"type":"object","properties":{"feature":{"type":"string"},"status":{"type":"string","enum":["available","warning","missing","unknown"]}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /register\_child

> \*\*Legacy\*\* - use \*\*POST \[\`/partners/\<uuid\_str:partner\_org\_id>/orgs\`]\(#tag/Organizations/paths/\~1v2\~1partners\~1{partner\_org\_id}\~1orgs/post)\*\* instead. This endpoint will be discontinued soon.\
> \
> Registers a new child organization under the channel partner. Creates the organization, sets up user memberships, and establishes the partnership relationship.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"partners","description":"partners api automation"}],"paths":{"/v2/org/{org_id}/partners/onboarding/register_child":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerRegisterOrgResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerRegisterOrg"}}}},"tags":["partners"],"summary":"/register_child","description":"**Legacy** - use **POST [`/partners/<uuid_str:partner_org_id>/orgs`](#tag/Organizations/paths/~1v2~1partners~1{partner_org_id}~1orgs/post)** instead. This endpoint will be discontinued soon.\n\nRegisters a new child organization under the channel partner. Creates the organization, sets up user memberships, and establishes the partnership relationship.","deprecated":true}}},"components":{"schemas":{"PartnerRegisterOrgResponse":{"type":"object","properties":{"org_id":{"type":"string"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"PartnerRegisterOrg":{"type":"object","properties":{"company":{"type":"string"},"labra_subscription_id":{"type":"string"},"email":{"type":["string","null"],"format":"email","default":null,"maxLength":255}},"required":["company"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /start

> Starts the onboarding process for an organization. Creates or retrieves an onboarding record and sets the provider to AWS.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"partners","description":"partners api automation"}],"paths":{"/v2/org/{org_id}/partners/onboarding/start":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartOnboarding"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["partners"],"summary":"/start","description":"Starts the onboarding process for an organization. Creates or retrieves an onboarding record and sets the provider to AWS."}}},"components":{"schemas":{"StartOnboarding":{"type":"object","properties":{"onboarding_id":{"type":"string"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /child-orgs

> Lists child organizations. This returns all orgs belongs to the channel partner identified by \*\*org\_id\*\*.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"partners","description":"partners api automation"}],"paths":{"/v2/org/{org_id}/partners/onboarding/child-orgs":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ListChildOrgsResponse"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["partners"],"summary":"/child-orgs","description":"Lists child organizations. This returns all orgs belongs to the channel partner identified by **org_id**."}}},"components":{"schemas":{"ListChildOrgsResponse":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"org_id":{"type":"string"},"org_name":{"type":"string"},"org_checklist":{"type":"array","items":{"$ref":"#/components/schemas/Validation"}},"integration_checklist":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/Validation"}}}},"required":["created_at","integration_checklist","org_checklist","org_id","org_name"],"additionalProperties":false},"Validation":{"type":"object","properties":{"feature":{"type":"string"},"status":{"type":"string","enum":["available","warning","missing","unknown"]}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /recommended

> Gets recommended purchase plans for a specific provider. Returns the most suitable plan based on the organization and provider requirements.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"partners","description":"partners api automation"}],"paths":{"/v2/org/{org_id}/partners/purchase-plans-v2/recommended":{"get":{"parameters":[{"in":"query","name":"provider","schema":{"enum":["aws","azure","gcp","unknown"],"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchasePlanV2CombinedSummary"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["partners"],"summary":"/recommended","description":"Gets recommended purchase plans for a specific provider. Returns the most suitable plan based on the organization and provider requirements."}}},"components":{"schemas":{"PurchasePlanV2CombinedSummary":{"type":"object","properties":{"start_date":{"type":["string","null"],"format":"date-time"},"end_date":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"data_source":{"type":"string","maxLength":20},"name":{"type":"string"},"description":{"type":["string","null"]},"segment_id":{"type":"string","maxLength":50},"meta_plan_id":{"type":["string","null"],"format":"uuid"},"org_id":{"type":"string","maxLength":50},"last_modified":{"type":["string","null"],"format":"date-time"},"plan_type":{"type":"string","enum":["purchase","renewal","infrastructure"]},"coverage_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"is_calculating":{"type":"boolean"},"is_saved":{"type":"boolean"},"is_locked":{"type":"boolean"},"max_upfront_cost":{"type":"number"},"minimum_upfront_interest_rate":{"type":"number"},"preferred_payment_option":{"enum":["No Upfront","Partial Upfront","All Upfront",null]},"included_contract_specs":{"type":"array","items":{"$ref":"#/components/schemas/PurchasePlanContractSpec"}},"included_contract_terms":{"type":"array","items":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]}},"recommend_within_covered_accounts":{"type":["boolean","null"]},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_recommended":{"type":"boolean"},"is_default":{"type":"boolean"},"is_renewal":{"type":"boolean"},"execution_policy":{"$ref":"#/components/schemas/ExecutePurchasePolicyDump_Exclude_Segment_TargetPlan"},"segment":{"$ref":"#/components/schemas/SegmentInfo"},"flagged_actions":{"type":"array","items":{"$ref":"#/components/schemas/FlaggedAction"}},"created_by":{"$ref":"#/components/schemas/UserInfo"},"resource_ids":{"type":"array","items":{"type":"string"}},"reservation_ids":{"type":"array","items":{"type":"string"}},"max_term":{"type":"string"},"all_terms":{"type":"array","items":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]}},"covered_ondemand_cost":{"type":"number"},"before_ondemand_cost":{"type":"number"},"before_reserved_cost":{"type":"number"},"amortized_cost":{"type":"number"},"recurring_cost":{"type":"number"},"upfront_cost":{"type":"number"},"before_cost":{"type":"number"},"after_cost":{"type":"number"},"total_cost":{"type":"number"},"savings":{"type":"number"},"fee":{"type":"number"},"commitment_coverage":{"type":"number"},"minimum_commitment_cost":{"type":"number"},"breakeven_hours":{"type":"number"},"total_savings":{"type":"number"},"monthly_savings":{"type":"number"},"monthly_amortized_cost":{"type":"number"},"monthly_fee":{"type":"number"},"monthly_before_cost":{"type":"number"},"monthly_after_cost":{"type":"number"},"total_monthly_before_cost":{"type":"number"},"aggregate_metrics":{"$ref":"#/components/schemas/AggregateMetrics"},"summaries":{"type":"array","items":{"$ref":"#/components/schemas/LineItemSummary"}}},"required":["after_cost","all_terms","amortized_cost","before_cost","before_ondemand_cost","before_reserved_cost","breakeven_hours","commitment_coverage","coverage_id","covered_ondemand_cost","created_at","created_by","data_source","description","execution_policy","fee","flagged_actions","id","included_contract_specs","included_contract_terms","is_calculating","is_default","is_locked","is_recommended","is_renewal","is_saved","last_modified","max_term","max_upfront_cost","meta_plan_id","minimum_commitment_cost","minimum_upfront_interest_rate","monthly_after_cost","monthly_amortized_cost","monthly_before_cost","monthly_fee","monthly_savings","name","org_id","plan_type","preferred_payment_option","recommend_within_covered_accounts","recurring_cost","reservation_ids","resource_ids","savings","segment","segment_id","status","summaries","total_cost","total_monthly_before_cost","total_savings","upfront_cost"],"additionalProperties":false},"PurchasePlanContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string"},"properties":{"type":"object","default":{},"additionalProperties":{}},"term":{"default":null,"type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"payment_option":{"default":null,"type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]}},"required":["commitment_type"],"additionalProperties":false},"ExecutePurchasePolicyDump_Exclude_Segment_TargetPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"org_id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","readOnly":true},"description":{"type":["string","null"],"readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"last_modified":{"type":["string","null"],"format":"date-time","readOnly":true},"schedule":{"type":"string","enum":["quarterly","weekly","monthly","daily"],"readOnly":true},"start_date":{"type":["string","null"],"format":"date-time","readOnly":true},"end_date":{"type":["string","null"],"format":"date-time","readOnly":true},"enabled":{"type":"boolean","readOnly":true},"next_execution_date":{"type":["string","null"],"format":"date-time","readOnly":true},"meta_plan_id":{"type":["string","null"],"format":"uuid","readOnly":true},"segment_id":{"type":["string","null"],"format":"uuid","readOnly":true},"default_plan_name":{"type":["string","null"],"readOnly":true},"min_savings":{"type":["number","null"],"readOnly":true},"meta_plan":{"readOnly":true,"$ref":"#/components/schemas/MetaPlanInfo"},"created_by":{"readOnly":true,"$ref":"#/components/schemas/UserInfo"},"plans":{"readOnly":true,"type":"array","items":{"$ref":"#/components/schemas/PlanInfo"}},"total_savings":{"type":["number","null"],"readOnly":true}},"required":["created_at","created_by","default_plan_name","description","enabled","end_date","id","last_modified","meta_plan","meta_plan_id","min_savings","name","next_execution_date","org_id","plans","schedule","segment_id","start_date","total_savings"],"additionalProperties":false},"MetaPlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"is_default":{"type":"boolean","readOnly":true}},"required":["created_at","id","is_default","name"],"additionalProperties":false},"UserInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"username":{"type":"string","maxLength":255},"full_name":{"type":["string","null"],"maxLength":255}},"required":["username"],"additionalProperties":false},"PlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"status":{"readOnly":true,"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["created_at","id","name","status"],"additionalProperties":false},"SegmentInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"is_default":{"type":"boolean","readOnly":true},"provider":{"readOnly":true,"type":"string","enum":["aws","azure","gcp","unknown"]}},"required":["created_at","id","is_default","name","provider"],"additionalProperties":false},"FlaggedAction":{"oneOf":[{"$ref":"#/components/schemas/PurchaseAction_Exclude_User"},{"$ref":"#/components/schemas/RenewalPurchaseAction_Exclude_User"},{"$ref":"#/components/schemas/ExchangeAction_Exclude_User"},{"$ref":"#/components/schemas/LegacyPurchaseAction_Exclude_User"}],"discriminator":{"propertyName":"action_type","mapping":{"purchase":"#/components/schemas/PurchaseAction_Exclude_User","renewal_purchase":"#/components/schemas/RenewalPurchaseAction_Exclude_User","exchange":"#/components/schemas/ExchangeAction_Exclude_User","legacy_purchase":"#/components/schemas/LegacyPurchaseAction_Exclude_User"}}},"PurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"PurchasePlanV2NameId":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string","format":"uuid"},"is_default":{"type":"boolean"},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["id","is_default","name","status"],"additionalProperties":false},"RenewalPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"ExchangeAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"exchange_status":{"type":["string","null"],"maxLength":255}},"additionalProperties":false},"LegacyPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true}},"additionalProperties":false},"AggregateMetrics":{"type":"object","properties":{"potential_coverage":{"type":"number"},"current_coverage":{"type":"number"},"summaries":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CommitmentSummary"}}},"additionalProperties":false},"CommitmentSummary":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"provider":{"type":["string","null"],"enum":["aws","azure","gcp","unknown",null]},"service_name":{"type":"string"},"num_commitments":{"type":"integer"},"min_commitment":{"type":"number"},"max_savings":{"type":"number"},"min_savings":{"type":"number"},"upfront_cost":{"type":"number"},"monthly_savings":{"type":"number"},"monthly_commitment":{"type":"number"},"potential_coverage":{"type":"number"},"current_coverage":{"type":"number"},"min_term_hours":{"type":"integer"},"max_term_hours":{"type":"integer"},"gri_premium":{"type":"number"}},"required":["key"],"additionalProperties":false},"LineItemSummary":{"type":"object","properties":{"key":{"type":"string"},"provider":{"type":"string","enum":["aws","azure","gcp","unknown"]},"num_commitments":{"type":"integer"},"min_commitment":{"type":"number"},"max_savings":{"type":"number"},"min_savings":{"type":"number"},"upfront_cost":{"type":"number"},"monthly_savings":{"type":"number"},"monthly_commitment":{"type":"number"},"min_term_hours":{"type":"integer"},"max_term_hours":{"type":"integer"},"gri_premiums":{"type":"number"},"if_all_ondemand_cost":{"type":"number"},"before_ondemand_cost":{"type":"number"},"after_ondemand_cost":{"type":"number"}},"required":["after_ondemand_cost","before_ondemand_cost","gri_premiums","if_all_ondemand_cost","key","max_savings","max_term_hours","min_commitment","min_savings","min_term_hours","monthly_commitment","monthly_savings","num_commitments","provider","upfront_cost"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## /\<uuid:plan\_id>/purchase

> Executes purchase of a specific plan by plan ID. Creates or validates user membership and processes the plan purchase.

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"partners","description":"partners api automation"}],"paths":{"/v2/org/{org_id}/partners/purchase-plans-v2/{plan_id}/purchase":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchasePlanV2"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseRequest"}}}},"tags":["partners"],"summary":"/<uuid:plan_id>/purchase","description":"Executes purchase of a specific plan by plan ID. Creates or validates user membership and processes the plan purchase."}}},"components":{"schemas":{"PurchasePlanV2":{"type":"object","properties":{"start_date":{"type":["string","null"],"format":"date-time"},"end_date":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"data_source":{"type":"string","maxLength":20},"name":{"type":"string"},"description":{"type":["string","null"]},"segment_id":{"type":"string","maxLength":50},"meta_plan_id":{"type":["string","null"],"format":"uuid"},"org_id":{"type":"string","maxLength":50},"last_modified":{"type":["string","null"],"format":"date-time"},"plan_type":{"type":"string","enum":["purchase","renewal","infrastructure"]},"coverage_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"is_calculating":{"type":"boolean"},"is_saved":{"type":"boolean"},"is_locked":{"type":"boolean"},"max_upfront_cost":{"type":"number"},"minimum_upfront_interest_rate":{"type":"number"},"preferred_payment_option":{"enum":["No Upfront","Partial Upfront","All Upfront",null]},"included_contract_specs":{"type":"array","items":{"$ref":"#/components/schemas/PurchasePlanContractSpec"}},"included_contract_terms":{"type":"array","items":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]}},"recommend_within_covered_accounts":{"type":["boolean","null"]},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_recommended":{"type":"boolean"},"is_default":{"type":"boolean"},"is_renewal":{"type":"boolean"},"execution_policy":{"$ref":"#/components/schemas/ExecutePurchasePolicyDump_Exclude_Segment_TargetPlan"},"segment":{"$ref":"#/components/schemas/SegmentInfo"},"flagged_actions":{"type":"array","items":{"$ref":"#/components/schemas/FlaggedAction"}},"created_by":{"$ref":"#/components/schemas/UserInfo"},"resource_ids":{"type":"array","items":{"type":"string"}},"reservation_ids":{"type":"array","items":{"type":"string"}}},"required":["coverage_id","created_at","created_by","data_source","description","execution_policy","flagged_actions","id","included_contract_specs","included_contract_terms","is_calculating","is_default","is_locked","is_recommended","is_renewal","is_saved","last_modified","max_upfront_cost","meta_plan_id","minimum_upfront_interest_rate","name","org_id","plan_type","preferred_payment_option","recommend_within_covered_accounts","reservation_ids","resource_ids","segment","segment_id","status"],"additionalProperties":false},"PurchasePlanContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string"},"properties":{"type":"object","default":{},"additionalProperties":{}},"term":{"default":null,"type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"payment_option":{"default":null,"type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]}},"required":["commitment_type"],"additionalProperties":false},"ExecutePurchasePolicyDump_Exclude_Segment_TargetPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"org_id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","readOnly":true},"description":{"type":["string","null"],"readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"last_modified":{"type":["string","null"],"format":"date-time","readOnly":true},"schedule":{"type":"string","enum":["quarterly","weekly","monthly","daily"],"readOnly":true},"start_date":{"type":["string","null"],"format":"date-time","readOnly":true},"end_date":{"type":["string","null"],"format":"date-time","readOnly":true},"enabled":{"type":"boolean","readOnly":true},"next_execution_date":{"type":["string","null"],"format":"date-time","readOnly":true},"meta_plan_id":{"type":["string","null"],"format":"uuid","readOnly":true},"segment_id":{"type":["string","null"],"format":"uuid","readOnly":true},"default_plan_name":{"type":["string","null"],"readOnly":true},"min_savings":{"type":["number","null"],"readOnly":true},"meta_plan":{"readOnly":true,"$ref":"#/components/schemas/MetaPlanInfo"},"created_by":{"readOnly":true,"$ref":"#/components/schemas/UserInfo"},"plans":{"readOnly":true,"type":"array","items":{"$ref":"#/components/schemas/PlanInfo"}},"total_savings":{"type":["number","null"],"readOnly":true}},"required":["created_at","created_by","default_plan_name","description","enabled","end_date","id","last_modified","meta_plan","meta_plan_id","min_savings","name","next_execution_date","org_id","plans","schedule","segment_id","start_date","total_savings"],"additionalProperties":false},"MetaPlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"is_default":{"type":"boolean","readOnly":true}},"required":["created_at","id","is_default","name"],"additionalProperties":false},"UserInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"username":{"type":"string","maxLength":255},"full_name":{"type":["string","null"],"maxLength":255}},"required":["username"],"additionalProperties":false},"PlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"status":{"readOnly":true,"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["created_at","id","name","status"],"additionalProperties":false},"SegmentInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"is_default":{"type":"boolean","readOnly":true},"provider":{"readOnly":true,"type":"string","enum":["aws","azure","gcp","unknown"]}},"required":["created_at","id","is_default","name","provider"],"additionalProperties":false},"FlaggedAction":{"oneOf":[{"$ref":"#/components/schemas/PurchaseAction_Exclude_User"},{"$ref":"#/components/schemas/RenewalPurchaseAction_Exclude_User"},{"$ref":"#/components/schemas/ExchangeAction_Exclude_User"},{"$ref":"#/components/schemas/LegacyPurchaseAction_Exclude_User"}],"discriminator":{"propertyName":"action_type","mapping":{"purchase":"#/components/schemas/PurchaseAction_Exclude_User","renewal_purchase":"#/components/schemas/RenewalPurchaseAction_Exclude_User","exchange":"#/components/schemas/ExchangeAction_Exclude_User","legacy_purchase":"#/components/schemas/LegacyPurchaseAction_Exclude_User"}}},"PurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"PurchasePlanV2NameId":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string","format":"uuid"},"is_default":{"type":"boolean"},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["id","is_default","name","status"],"additionalProperties":false},"RenewalPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"ExchangeAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"exchange_status":{"type":["string","null"],"maxLength":255}},"additionalProperties":false},"LegacyPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"PurchaseRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":255,"description":"Email of the user executing the purchase"}},"required":["email"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## PATCH /v2/org/{org\_id}/partners

> Partially Update an Organization\
> So far the scope is only limited to marketplace offer links

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"tags":[{"name":"partners","description":"partners api automation"}],"paths":{"/v2/org/{org_id}/partners":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerOrgResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePartnerOrg"}}}},"summary":"Partially Update an Organization\nSo far the scope is only limited to marketplace offer links","tags":["partners"]}}},"components":{"schemas":{"PartnerOrgResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"aws_marketplace_offer_link":{"type":["string","null"]},"azure_marketplace_offer_link":{"type":["string","null"]},"gcp_marketplace_offer_link":{"type":["string","null"]}},"required":["aws_marketplace_offer_link","azure_marketplace_offer_link","gcp_marketplace_offer_link","id","name"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"UpdatePartnerOrg":{"type":"object","properties":{"aws_marketplace_offer_link":{"type":["string","null"],"format":"url"},"azure_marketplace_offer_link":{"type":["string","null"],"format":"url"},"gcp_marketplace_offer_link":{"type":["string","null"],"format":"url"}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Models

## The Error object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}}}
```

## The PaginationMetadata object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false}}}}
```

## The ApiErrorResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{},"code":{"type":["string","null"]},"url":{"type":["string","null"]},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]}}}}
```

## The UserInvite object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"UserInvite":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":255},"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"]}},"required":["email"],"additionalProperties":false}}}}
```

## The MutateAddress object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"MutateAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":["string","null"],"default":null},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"}},"required":["city","country","line1","state","zip"],"additionalProperties":false}}}}
```

## The RegisterOrg object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"RegisterOrg":{"type":"object","properties":{"name":{"type":"string"},"labra_subscription_id":{"type":"string"},"users":{"type":"array","items":{"$ref":"#/components/schemas/UserInvite"}},"domain":{"type":["string","null"]},"primary_address":{"anyOf":[{"$ref":"#/components/schemas/MutateAddress"},{"type":"null"}]},"aws_marketplace_offer_link":{"type":["string","null"],"format":"url"},"azure_marketplace_offer_link":{"type":["string","null"],"format":"url"},"gcp_marketplace_offer_link":{"type":["string","null"],"format":"url"}},"required":["name"],"additionalProperties":false},"UserInvite":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":255},"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"]}},"required":["email"],"additionalProperties":false},"MutateAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":["string","null"],"default":null},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"}},"required":["city","country","line1","state","zip"],"additionalProperties":false}}}}
```

## The OrgMembershipResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"OrgMembershipResponse":{"type":"object","properties":{"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"],"readOnly":true},"username":{"type":"string","format":"email","readOnly":true,"maxLength":255}},"additionalProperties":false}}}}
```

## The RegisterOrgResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"RegisterOrgResponse":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"memberships":{"readOnly":true,"type":"array","items":{"$ref":"#/components/schemas/OrgMembershipResponse"}},"domain":{"type":["string","null"],"readOnly":true},"primary_address":{"readOnly":true,"anyOf":[{"$ref":"#/components/schemas/MutateAddress"},{"type":"null"}]},"aws_marketplace_offer_link":{"type":["string","null"],"format":"url","readOnly":true},"azure_marketplace_offer_link":{"type":["string","null"],"format":"url","readOnly":true},"gcp_marketplace_offer_link":{"type":["string","null"],"format":"url","readOnly":true}},"required":["id","name"],"additionalProperties":false},"OrgMembershipResponse":{"type":"object","properties":{"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"],"readOnly":true},"username":{"type":"string","format":"email","readOnly":true,"maxLength":255}},"additionalProperties":false},"MutateAddress":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":["string","null"],"default":null},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"}},"required":["city","country","line1","state","zip"],"additionalProperties":false}}}}
```

## The InviteUsers object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"InviteUsers":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/UserInvite"}}},"required":["users"],"additionalProperties":false},"UserInvite":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":255},"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"]}},"required":["email"],"additionalProperties":false}}}}
```

## The CloudFormation object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"CloudFormation":{"type":"object","properties":{"template":{"type":"object","additionalProperties":{}}},"additionalProperties":false}}}}
```

## The LaunchStackUrls object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"LaunchStackUrls":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":false}}}}
```

## The ExistingCUR object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"ExistingCUR":{"type":"object","properties":{"region":{"type":"string"},"bucket":{"type":"string"},"prefix":{"type":"string"},"report_name":{"type":"string"}},"required":["bucket","prefix","region","report_name"],"additionalProperties":false}}}}
```

## The VerificationArgs object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"VerificationArgs":{"type":"object","properties":{"onboarding_id":{"type":"string","pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"account_id":{"type":"string"},"read_only":{"type":"boolean","default":false},"existing_cur":{"$ref":"#/components/schemas/ExistingCUR"}},"additionalProperties":false},"ExistingCUR":{"type":"object","properties":{"region":{"type":"string"},"bucket":{"type":"string"},"prefix":{"type":"string"},"report_name":{"type":"string"}},"required":["bucket","prefix","region","report_name"],"additionalProperties":false}}}}
```

## The Validation object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"Validation":{"type":"object","properties":{"feature":{"type":"string"},"status":{"type":"string","enum":["available","warning","missing","unknown"]}},"additionalProperties":false}}}}
```

## The AzureAuthUrlArgs object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"AzureAuthUrlArgs":{"type":"object","properties":{"azure_tenant_id":{"type":"string"},"azure_subscription_id":{"type":"string"}},"required":["azure_subscription_id","azure_tenant_id"],"additionalProperties":false}}}}
```

## The AzureAuthUrlResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"AzureAuthUrlResponse":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"],"additionalProperties":false}}}}
```

## The PartnerRegisterOrg object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"PartnerRegisterOrg":{"type":"object","properties":{"company":{"type":"string"},"labra_subscription_id":{"type":"string"},"email":{"type":["string","null"],"format":"email","default":null,"maxLength":255}},"required":["company"],"additionalProperties":false}}}}
```

## The PartnerRegisterOrgResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"PartnerRegisterOrgResponse":{"type":"object","properties":{"org_id":{"type":"string"}},"additionalProperties":false}}}}
```

## The StartOnboarding object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"StartOnboarding":{"type":"object","properties":{"onboarding_id":{"type":"string"}},"additionalProperties":false}}}}
```

## The ListChildOrgsResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"ListChildOrgsResponse":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"org_id":{"type":"string"},"org_name":{"type":"string"},"org_checklist":{"type":"array","items":{"$ref":"#/components/schemas/Validation"}},"integration_checklist":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/Validation"}}}},"required":["created_at","integration_checklist","org_checklist","org_id","org_name"],"additionalProperties":false},"Validation":{"type":"object","properties":{"feature":{"type":"string"},"status":{"type":"string","enum":["available","warning","missing","unknown"]}},"additionalProperties":false}}}}
```

## The PurchasePlanContractSpec object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"PurchasePlanContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string"},"properties":{"type":"object","default":{},"additionalProperties":{}},"term":{"default":null,"type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"payment_option":{"default":null,"type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]}},"required":["commitment_type"],"additionalProperties":false}}}}
```

## The MetaPlanInfo object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"MetaPlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"is_default":{"type":"boolean","readOnly":true}},"required":["created_at","id","is_default","name"],"additionalProperties":false}}}}
```

## The UserInfo object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"UserInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"username":{"type":"string","maxLength":255},"full_name":{"type":["string","null"],"maxLength":255}},"required":["username"],"additionalProperties":false}}}}
```

## The PlanInfo object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"PlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"status":{"readOnly":true,"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["created_at","id","name","status"],"additionalProperties":false}}}}
```

## The ExecutePurchasePolicyDump\_Exclude\_Segment\_TargetPlan object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"ExecutePurchasePolicyDump_Exclude_Segment_TargetPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"org_id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","readOnly":true},"description":{"type":["string","null"],"readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"last_modified":{"type":["string","null"],"format":"date-time","readOnly":true},"schedule":{"type":"string","enum":["quarterly","weekly","monthly","daily"],"readOnly":true},"start_date":{"type":["string","null"],"format":"date-time","readOnly":true},"end_date":{"type":["string","null"],"format":"date-time","readOnly":true},"enabled":{"type":"boolean","readOnly":true},"next_execution_date":{"type":["string","null"],"format":"date-time","readOnly":true},"meta_plan_id":{"type":["string","null"],"format":"uuid","readOnly":true},"segment_id":{"type":["string","null"],"format":"uuid","readOnly":true},"default_plan_name":{"type":["string","null"],"readOnly":true},"min_savings":{"type":["number","null"],"readOnly":true},"meta_plan":{"readOnly":true,"$ref":"#/components/schemas/MetaPlanInfo"},"created_by":{"readOnly":true,"$ref":"#/components/schemas/UserInfo"},"plans":{"readOnly":true,"type":"array","items":{"$ref":"#/components/schemas/PlanInfo"}},"total_savings":{"type":["number","null"],"readOnly":true}},"required":["created_at","created_by","default_plan_name","description","enabled","end_date","id","last_modified","meta_plan","meta_plan_id","min_savings","name","next_execution_date","org_id","plans","schedule","segment_id","start_date","total_savings"],"additionalProperties":false},"MetaPlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"is_default":{"type":"boolean","readOnly":true}},"required":["created_at","id","is_default","name"],"additionalProperties":false},"UserInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"username":{"type":"string","maxLength":255},"full_name":{"type":["string","null"],"maxLength":255}},"required":["username"],"additionalProperties":false},"PlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"status":{"readOnly":true,"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["created_at","id","name","status"],"additionalProperties":false}}}}
```

## The SegmentInfo object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"SegmentInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"is_default":{"type":"boolean","readOnly":true},"provider":{"readOnly":true,"type":"string","enum":["aws","azure","gcp","unknown"]}},"required":["created_at","id","is_default","name","provider"],"additionalProperties":false}}}}
```

## The PurchasePlanV2NameId object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"PurchasePlanV2NameId":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string","format":"uuid"},"is_default":{"type":"boolean"},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["id","is_default","name","status"],"additionalProperties":false}}}}
```

## The PurchaseAction\_Exclude\_User object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"PurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"PurchasePlanV2NameId":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string","format":"uuid"},"is_default":{"type":"boolean"},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["id","is_default","name","status"],"additionalProperties":false}}}}
```

## The RenewalPurchaseAction\_Exclude\_User object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"RenewalPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"PurchasePlanV2NameId":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string","format":"uuid"},"is_default":{"type":"boolean"},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["id","is_default","name","status"],"additionalProperties":false}}}}
```

## The ExchangeAction\_Exclude\_User object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"ExchangeAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"exchange_status":{"type":["string","null"],"maxLength":255}},"additionalProperties":false}}}}
```

## The LegacyPurchaseAction\_Exclude\_User object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"LegacyPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true}},"additionalProperties":false}}}}
```

## The FlaggedAction object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"FlaggedAction":{"oneOf":[{"$ref":"#/components/schemas/PurchaseAction_Exclude_User"},{"$ref":"#/components/schemas/RenewalPurchaseAction_Exclude_User"},{"$ref":"#/components/schemas/ExchangeAction_Exclude_User"},{"$ref":"#/components/schemas/LegacyPurchaseAction_Exclude_User"}],"discriminator":{"propertyName":"action_type","mapping":{"purchase":"#/components/schemas/PurchaseAction_Exclude_User","renewal_purchase":"#/components/schemas/RenewalPurchaseAction_Exclude_User","exchange":"#/components/schemas/ExchangeAction_Exclude_User","legacy_purchase":"#/components/schemas/LegacyPurchaseAction_Exclude_User"}}},"PurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"PurchasePlanV2NameId":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string","format":"uuid"},"is_default":{"type":"boolean"},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["id","is_default","name","status"],"additionalProperties":false},"RenewalPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"ExchangeAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"exchange_status":{"type":["string","null"],"maxLength":255}},"additionalProperties":false},"LegacyPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true}},"additionalProperties":false}}}}
```

## The CommitmentSummary object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"CommitmentSummary":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"provider":{"type":["string","null"],"enum":["aws","azure","gcp","unknown",null]},"service_name":{"type":"string"},"num_commitments":{"type":"integer"},"min_commitment":{"type":"number"},"max_savings":{"type":"number"},"min_savings":{"type":"number"},"upfront_cost":{"type":"number"},"monthly_savings":{"type":"number"},"monthly_commitment":{"type":"number"},"potential_coverage":{"type":"number"},"current_coverage":{"type":"number"},"min_term_hours":{"type":"integer"},"max_term_hours":{"type":"integer"},"gri_premium":{"type":"number"}},"required":["key"],"additionalProperties":false}}}}
```

## The AggregateMetrics object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"AggregateMetrics":{"type":"object","properties":{"potential_coverage":{"type":"number"},"current_coverage":{"type":"number"},"summaries":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CommitmentSummary"}}},"additionalProperties":false},"CommitmentSummary":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"provider":{"type":["string","null"],"enum":["aws","azure","gcp","unknown",null]},"service_name":{"type":"string"},"num_commitments":{"type":"integer"},"min_commitment":{"type":"number"},"max_savings":{"type":"number"},"min_savings":{"type":"number"},"upfront_cost":{"type":"number"},"monthly_savings":{"type":"number"},"monthly_commitment":{"type":"number"},"potential_coverage":{"type":"number"},"current_coverage":{"type":"number"},"min_term_hours":{"type":"integer"},"max_term_hours":{"type":"integer"},"gri_premium":{"type":"number"}},"required":["key"],"additionalProperties":false}}}}
```

## The LineItemSummary object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"LineItemSummary":{"type":"object","properties":{"key":{"type":"string"},"provider":{"type":"string","enum":["aws","azure","gcp","unknown"]},"num_commitments":{"type":"integer"},"min_commitment":{"type":"number"},"max_savings":{"type":"number"},"min_savings":{"type":"number"},"upfront_cost":{"type":"number"},"monthly_savings":{"type":"number"},"monthly_commitment":{"type":"number"},"min_term_hours":{"type":"integer"},"max_term_hours":{"type":"integer"},"gri_premiums":{"type":"number"},"if_all_ondemand_cost":{"type":"number"},"before_ondemand_cost":{"type":"number"},"after_ondemand_cost":{"type":"number"}},"required":["after_ondemand_cost","before_ondemand_cost","gri_premiums","if_all_ondemand_cost","key","max_savings","max_term_hours","min_commitment","min_savings","min_term_hours","monthly_commitment","monthly_savings","num_commitments","provider","upfront_cost"],"additionalProperties":false}}}}
```

## The PurchasePlanV2CombinedSummary object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"PurchasePlanV2CombinedSummary":{"type":"object","properties":{"start_date":{"type":["string","null"],"format":"date-time"},"end_date":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"data_source":{"type":"string","maxLength":20},"name":{"type":"string"},"description":{"type":["string","null"]},"segment_id":{"type":"string","maxLength":50},"meta_plan_id":{"type":["string","null"],"format":"uuid"},"org_id":{"type":"string","maxLength":50},"last_modified":{"type":["string","null"],"format":"date-time"},"plan_type":{"type":"string","enum":["purchase","renewal","infrastructure"]},"coverage_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"is_calculating":{"type":"boolean"},"is_saved":{"type":"boolean"},"is_locked":{"type":"boolean"},"max_upfront_cost":{"type":"number"},"minimum_upfront_interest_rate":{"type":"number"},"preferred_payment_option":{"enum":["No Upfront","Partial Upfront","All Upfront",null]},"included_contract_specs":{"type":"array","items":{"$ref":"#/components/schemas/PurchasePlanContractSpec"}},"included_contract_terms":{"type":"array","items":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]}},"recommend_within_covered_accounts":{"type":["boolean","null"]},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_recommended":{"type":"boolean"},"is_default":{"type":"boolean"},"is_renewal":{"type":"boolean"},"execution_policy":{"$ref":"#/components/schemas/ExecutePurchasePolicyDump_Exclude_Segment_TargetPlan"},"segment":{"$ref":"#/components/schemas/SegmentInfo"},"flagged_actions":{"type":"array","items":{"$ref":"#/components/schemas/FlaggedAction"}},"created_by":{"$ref":"#/components/schemas/UserInfo"},"resource_ids":{"type":"array","items":{"type":"string"}},"reservation_ids":{"type":"array","items":{"type":"string"}},"max_term":{"type":"string"},"all_terms":{"type":"array","items":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]}},"covered_ondemand_cost":{"type":"number"},"before_ondemand_cost":{"type":"number"},"before_reserved_cost":{"type":"number"},"amortized_cost":{"type":"number"},"recurring_cost":{"type":"number"},"upfront_cost":{"type":"number"},"before_cost":{"type":"number"},"after_cost":{"type":"number"},"total_cost":{"type":"number"},"savings":{"type":"number"},"fee":{"type":"number"},"commitment_coverage":{"type":"number"},"minimum_commitment_cost":{"type":"number"},"breakeven_hours":{"type":"number"},"total_savings":{"type":"number"},"monthly_savings":{"type":"number"},"monthly_amortized_cost":{"type":"number"},"monthly_fee":{"type":"number"},"monthly_before_cost":{"type":"number"},"monthly_after_cost":{"type":"number"},"total_monthly_before_cost":{"type":"number"},"aggregate_metrics":{"$ref":"#/components/schemas/AggregateMetrics"},"summaries":{"type":"array","items":{"$ref":"#/components/schemas/LineItemSummary"}}},"required":["after_cost","all_terms","amortized_cost","before_cost","before_ondemand_cost","before_reserved_cost","breakeven_hours","commitment_coverage","coverage_id","covered_ondemand_cost","created_at","created_by","data_source","description","execution_policy","fee","flagged_actions","id","included_contract_specs","included_contract_terms","is_calculating","is_default","is_locked","is_recommended","is_renewal","is_saved","last_modified","max_term","max_upfront_cost","meta_plan_id","minimum_commitment_cost","minimum_upfront_interest_rate","monthly_after_cost","monthly_amortized_cost","monthly_before_cost","monthly_fee","monthly_savings","name","org_id","plan_type","preferred_payment_option","recommend_within_covered_accounts","recurring_cost","reservation_ids","resource_ids","savings","segment","segment_id","status","summaries","total_cost","total_monthly_before_cost","total_savings","upfront_cost"],"additionalProperties":false},"PurchasePlanContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string"},"properties":{"type":"object","default":{},"additionalProperties":{}},"term":{"default":null,"type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"payment_option":{"default":null,"type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]}},"required":["commitment_type"],"additionalProperties":false},"ExecutePurchasePolicyDump_Exclude_Segment_TargetPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"org_id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","readOnly":true},"description":{"type":["string","null"],"readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"last_modified":{"type":["string","null"],"format":"date-time","readOnly":true},"schedule":{"type":"string","enum":["quarterly","weekly","monthly","daily"],"readOnly":true},"start_date":{"type":["string","null"],"format":"date-time","readOnly":true},"end_date":{"type":["string","null"],"format":"date-time","readOnly":true},"enabled":{"type":"boolean","readOnly":true},"next_execution_date":{"type":["string","null"],"format":"date-time","readOnly":true},"meta_plan_id":{"type":["string","null"],"format":"uuid","readOnly":true},"segment_id":{"type":["string","null"],"format":"uuid","readOnly":true},"default_plan_name":{"type":["string","null"],"readOnly":true},"min_savings":{"type":["number","null"],"readOnly":true},"meta_plan":{"readOnly":true,"$ref":"#/components/schemas/MetaPlanInfo"},"created_by":{"readOnly":true,"$ref":"#/components/schemas/UserInfo"},"plans":{"readOnly":true,"type":"array","items":{"$ref":"#/components/schemas/PlanInfo"}},"total_savings":{"type":["number","null"],"readOnly":true}},"required":["created_at","created_by","default_plan_name","description","enabled","end_date","id","last_modified","meta_plan","meta_plan_id","min_savings","name","next_execution_date","org_id","plans","schedule","segment_id","start_date","total_savings"],"additionalProperties":false},"MetaPlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"is_default":{"type":"boolean","readOnly":true}},"required":["created_at","id","is_default","name"],"additionalProperties":false},"UserInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"username":{"type":"string","maxLength":255},"full_name":{"type":["string","null"],"maxLength":255}},"required":["username"],"additionalProperties":false},"PlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"status":{"readOnly":true,"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["created_at","id","name","status"],"additionalProperties":false},"SegmentInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"is_default":{"type":"boolean","readOnly":true},"provider":{"readOnly":true,"type":"string","enum":["aws","azure","gcp","unknown"]}},"required":["created_at","id","is_default","name","provider"],"additionalProperties":false},"FlaggedAction":{"oneOf":[{"$ref":"#/components/schemas/PurchaseAction_Exclude_User"},{"$ref":"#/components/schemas/RenewalPurchaseAction_Exclude_User"},{"$ref":"#/components/schemas/ExchangeAction_Exclude_User"},{"$ref":"#/components/schemas/LegacyPurchaseAction_Exclude_User"}],"discriminator":{"propertyName":"action_type","mapping":{"purchase":"#/components/schemas/PurchaseAction_Exclude_User","renewal_purchase":"#/components/schemas/RenewalPurchaseAction_Exclude_User","exchange":"#/components/schemas/ExchangeAction_Exclude_User","legacy_purchase":"#/components/schemas/LegacyPurchaseAction_Exclude_User"}}},"PurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"PurchasePlanV2NameId":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string","format":"uuid"},"is_default":{"type":"boolean"},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["id","is_default","name","status"],"additionalProperties":false},"RenewalPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"ExchangeAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"exchange_status":{"type":["string","null"],"maxLength":255}},"additionalProperties":false},"LegacyPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true}},"additionalProperties":false},"AggregateMetrics":{"type":"object","properties":{"potential_coverage":{"type":"number"},"current_coverage":{"type":"number"},"summaries":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CommitmentSummary"}}},"additionalProperties":false},"CommitmentSummary":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"provider":{"type":["string","null"],"enum":["aws","azure","gcp","unknown",null]},"service_name":{"type":"string"},"num_commitments":{"type":"integer"},"min_commitment":{"type":"number"},"max_savings":{"type":"number"},"min_savings":{"type":"number"},"upfront_cost":{"type":"number"},"monthly_savings":{"type":"number"},"monthly_commitment":{"type":"number"},"potential_coverage":{"type":"number"},"current_coverage":{"type":"number"},"min_term_hours":{"type":"integer"},"max_term_hours":{"type":"integer"},"gri_premium":{"type":"number"}},"required":["key"],"additionalProperties":false},"LineItemSummary":{"type":"object","properties":{"key":{"type":"string"},"provider":{"type":"string","enum":["aws","azure","gcp","unknown"]},"num_commitments":{"type":"integer"},"min_commitment":{"type":"number"},"max_savings":{"type":"number"},"min_savings":{"type":"number"},"upfront_cost":{"type":"number"},"monthly_savings":{"type":"number"},"monthly_commitment":{"type":"number"},"min_term_hours":{"type":"integer"},"max_term_hours":{"type":"integer"},"gri_premiums":{"type":"number"},"if_all_ondemand_cost":{"type":"number"},"before_ondemand_cost":{"type":"number"},"after_ondemand_cost":{"type":"number"}},"required":["after_ondemand_cost","before_ondemand_cost","gri_premiums","if_all_ondemand_cost","key","max_savings","max_term_hours","min_commitment","min_savings","min_term_hours","monthly_commitment","monthly_savings","num_commitments","provider","upfront_cost"],"additionalProperties":false}}}}
```

## The PurchaseRequest object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"PurchaseRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":255,"description":"Email of the user executing the purchase"}},"required":["email"],"additionalProperties":false}}}}
```

## The PurchasePlanV2 object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"PurchasePlanV2":{"type":"object","properties":{"start_date":{"type":["string","null"],"format":"date-time"},"end_date":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","format":"uuid"},"data_source":{"type":"string","maxLength":20},"name":{"type":"string"},"description":{"type":["string","null"]},"segment_id":{"type":"string","maxLength":50},"meta_plan_id":{"type":["string","null"],"format":"uuid"},"org_id":{"type":"string","maxLength":50},"last_modified":{"type":["string","null"],"format":"date-time"},"plan_type":{"type":"string","enum":["purchase","renewal","infrastructure"]},"coverage_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"is_calculating":{"type":"boolean"},"is_saved":{"type":"boolean"},"is_locked":{"type":"boolean"},"max_upfront_cost":{"type":"number"},"minimum_upfront_interest_rate":{"type":"number"},"preferred_payment_option":{"enum":["No Upfront","Partial Upfront","All Upfront",null]},"included_contract_specs":{"type":"array","items":{"$ref":"#/components/schemas/PurchasePlanContractSpec"}},"included_contract_terms":{"type":"array","items":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]}},"recommend_within_covered_accounts":{"type":["boolean","null"]},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_recommended":{"type":"boolean"},"is_default":{"type":"boolean"},"is_renewal":{"type":"boolean"},"execution_policy":{"$ref":"#/components/schemas/ExecutePurchasePolicyDump_Exclude_Segment_TargetPlan"},"segment":{"$ref":"#/components/schemas/SegmentInfo"},"flagged_actions":{"type":"array","items":{"$ref":"#/components/schemas/FlaggedAction"}},"created_by":{"$ref":"#/components/schemas/UserInfo"},"resource_ids":{"type":"array","items":{"type":"string"}},"reservation_ids":{"type":"array","items":{"type":"string"}}},"required":["coverage_id","created_at","created_by","data_source","description","execution_policy","flagged_actions","id","included_contract_specs","included_contract_terms","is_calculating","is_default","is_locked","is_recommended","is_renewal","is_saved","last_modified","max_upfront_cost","meta_plan_id","minimum_upfront_interest_rate","name","org_id","plan_type","preferred_payment_option","recommend_within_covered_accounts","reservation_ids","resource_ids","segment","segment_id","status"],"additionalProperties":false},"PurchasePlanContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string"},"properties":{"type":"object","default":{},"additionalProperties":{}},"term":{"default":null,"type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"payment_option":{"default":null,"type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]}},"required":["commitment_type"],"additionalProperties":false},"ExecutePurchasePolicyDump_Exclude_Segment_TargetPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"org_id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","readOnly":true},"description":{"type":["string","null"],"readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"last_modified":{"type":["string","null"],"format":"date-time","readOnly":true},"schedule":{"type":"string","enum":["quarterly","weekly","monthly","daily"],"readOnly":true},"start_date":{"type":["string","null"],"format":"date-time","readOnly":true},"end_date":{"type":["string","null"],"format":"date-time","readOnly":true},"enabled":{"type":"boolean","readOnly":true},"next_execution_date":{"type":["string","null"],"format":"date-time","readOnly":true},"meta_plan_id":{"type":["string","null"],"format":"uuid","readOnly":true},"segment_id":{"type":["string","null"],"format":"uuid","readOnly":true},"default_plan_name":{"type":["string","null"],"readOnly":true},"min_savings":{"type":["number","null"],"readOnly":true},"meta_plan":{"readOnly":true,"$ref":"#/components/schemas/MetaPlanInfo"},"created_by":{"readOnly":true,"$ref":"#/components/schemas/UserInfo"},"plans":{"readOnly":true,"type":"array","items":{"$ref":"#/components/schemas/PlanInfo"}},"total_savings":{"type":["number","null"],"readOnly":true}},"required":["created_at","created_by","default_plan_name","description","enabled","end_date","id","last_modified","meta_plan","meta_plan_id","min_savings","name","next_execution_date","org_id","plans","schedule","segment_id","start_date","total_savings"],"additionalProperties":false},"MetaPlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"is_default":{"type":"boolean","readOnly":true}},"required":["created_at","id","is_default","name"],"additionalProperties":false},"UserInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"username":{"type":"string","maxLength":255},"full_name":{"type":["string","null"],"maxLength":255}},"required":["username"],"additionalProperties":false},"PlanInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"status":{"readOnly":true,"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["created_at","id","name","status"],"additionalProperties":false},"SegmentInfo":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"is_default":{"type":"boolean","readOnly":true},"provider":{"readOnly":true,"type":"string","enum":["aws","azure","gcp","unknown"]}},"required":["created_at","id","is_default","name","provider"],"additionalProperties":false},"FlaggedAction":{"oneOf":[{"$ref":"#/components/schemas/PurchaseAction_Exclude_User"},{"$ref":"#/components/schemas/RenewalPurchaseAction_Exclude_User"},{"$ref":"#/components/schemas/ExchangeAction_Exclude_User"},{"$ref":"#/components/schemas/LegacyPurchaseAction_Exclude_User"}],"discriminator":{"propertyName":"action_type","mapping":{"purchase":"#/components/schemas/PurchaseAction_Exclude_User","renewal_purchase":"#/components/schemas/RenewalPurchaseAction_Exclude_User","exchange":"#/components/schemas/ExchangeAction_Exclude_User","legacy_purchase":"#/components/schemas/LegacyPurchaseAction_Exclude_User"}}},"PurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"PurchasePlanV2NameId":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string","format":"uuid"},"is_default":{"type":"boolean"},"status":{"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]}},"required":["id","is_default","name","status"],"additionalProperties":false},"RenewalPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"plan_id":{"type":"string","readOnly":true,"pattern":"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\Z"},"plan":{"readOnly":true,"$ref":"#/components/schemas/PurchasePlanV2NameId"}},"required":["plan_id"],"additionalProperties":false},"ExchangeAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true},"exchange_status":{"type":["string","null"],"maxLength":255}},"additionalProperties":false},"LegacyPurchaseAction_Exclude_User":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"maxLength":50},"org_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"user_id":{"type":["string","null"],"readOnly":true,"maxLength":50},"provider":{"type":["string","null"],"maxLength":255},"action_type":{"type":["string","null"],"maxLength":255},"action_description":{},"status":{"type":["string","null"],"default":"submitted","maxLength":255},"creation_time":{"type":"string","format":"date-time","readOnly":true},"execution_time":{"type":["string","null"],"format":"date-time","readOnly":true},"execution_info":{"readOnly":true}},"additionalProperties":false}}}}
```

## The UpdatePartnerOrg object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"UpdatePartnerOrg":{"type":"object","properties":{"aws_marketplace_offer_link":{"type":["string","null"],"format":"url"},"azure_marketplace_offer_link":{"type":["string","null"],"format":"url"},"gcp_marketplace_offer_link":{"type":["string","null"],"format":"url"}},"additionalProperties":false}}}}
```

## The PartnerOrgResponse object

```json
{"openapi":"3.1.0","info":{"title":"Archera.ai Channel Partner API","version":"v1.0.0"},"components":{"schemas":{"PartnerOrgResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"aws_marketplace_offer_link":{"type":["string","null"]},"azure_marketplace_offer_link":{"type":["string","null"]},"gcp_marketplace_offer_link":{"type":["string","null"]}},"required":["aws_marketplace_offer_link","azure_marketplace_offer_link","gcp_marketplace_offer_link","id","name"],"additionalProperties":false}}}}
```


# Beta API

The Archera Beta API provides early access to features under active development — account-level\
billing data, new report types, and capabilities that haven't yet graduated to the stable API\
surface. Use it to build ahead of general availability, prototype integrations against real\
production data, and give feedback that shapes how these features ship.

Built for developers who need more than the stable API today, the Beta API lets you pull per-account\
cost breakdowns, access emerging data models, and integrate new capabilities directly into your\
platform. All endpoints are versioned at /beta/v1 and authenticated with your existing API key — no\
separate credentials required. Expect a faster release cadence and a shorter path from request to\
endpoint than you'd find anywhere else in the API.


# API Key Access

To use this API, you need an API key. Use the `x-api-key` header:

```bash
curl -H 'x-api-key: YOUR_API_KEY' https://api.archera.ai/beta/v1/...
```


# Units Convention

How to interpret monetary values in responses:

* **Monthly-rate endpoints** (e.g. `/commitments`, `/commitment-plans`, `/commitments/summary`, `/metrics/overview`, `/moneyback-guarantees/savings`): monetary fields are **monthly rates** based on a 730-hour month (8760 hours / 12 months — an annual-average month, NOT a calendar month, which varies 672-744 hours). A field labeled "monthly" reflects a per-730-hour figure, not a specific calendar month's total.
* **Aggregated metrics / time-series endpoints** (e.g. `/metrics/daily-savings`, `/metrics/daily-reservable-cost`, `/commitments/metrics`): top-level monetary fields are **sums over the requested date range**, and values in `daily` rows are **sums for that day**. Neither is a monthly rate; magnitude scales with range length.
* **`commitment_upfront_cost`** (top-level on individual commitments, plans, and plan line items — a sibling of `commitment_financials_monthly_rate`): **one-time total dollars** paid at signing — not a rate. Do not sum with monthly-rate fields. Omitted on aggregates (summary, metrics, invoices) where a summed upfront is not meaningful.


# Reports

Report download operations

## Partner Archera Premiums and Rebates by Organization

> Monthly allocation of Archera premiums, rebates, and savings across child organizations for a channel partner. One row per child org with that org's invoice totals.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"reports","description":"Report download operations"}],"paths":{"/beta/v1/org/{org_id}/reports/partner_archera_premiums_and_rebates_by_child_org":{"get":{"parameters":[{"in":"query","name":"format","description":"Response format: 'json' (default) or 'csv'","schema":{"type":"string","default":"json","enum":["json","csv"]},"required":false},{"in":"query","name":"year","description":"Billing year (e.g. 2026)","schema":{"type":"integer"},"required":true},{"in":"query","name":"month","description":"Billing month (1-12)","schema":{"type":"integer","minimum":1,"maximum":12},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PartnerArcheraPremiumsAndRebatesByChildOrgOutput"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["reports"],"summary":"Partner Archera Premiums and Rebates by Organization","description":"Monthly allocation of Archera premiums, rebates, and savings across child organizations for a channel partner. One row per child org with that org's invoice totals."}}},"components":{"schemas":{"PartnerArcheraPremiumsAndRebatesByChildOrgOutput":{"type":"object","properties":{"org_id":{"type":"string","description":"Child organization identifier"},"org_name":{"type":"string","description":"Child organization name"},"archera_premiums":{"type":"number","description":"Archera premiums for this organization"},"rebates":{"type":"number","description":"Rebates for this organization"},"gross_savings":{"type":"number","description":"Gross savings for this organization"},"net_savings":{"type":"number","description":"Net savings for this organization"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Archera Premiums and Rebates by Account

> Monthly allocation of Archera premiums, rebates, and savings by cloud account.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"reports","description":"Report download operations"}],"paths":{"/beta/v1/org/{org_id}/reports/archera_premiums_and_rebates_by_account":{"get":{"parameters":[{"in":"query","name":"format","description":"Response format: 'json' (default) or 'csv'","schema":{"type":"string","default":"json","enum":["json","csv"]},"required":false},{"in":"query","name":"year","description":"Billing year (e.g. 2026)","schema":{"type":"integer"},"required":true},{"in":"query","name":"month","description":"Billing month (1-12)","schema":{"type":"integer","minimum":1,"maximum":12},"required":true},{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp, unknown)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ArcheraPremiumsAndRebatesByAccountOutput"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["reports"],"summary":"Archera Premiums and Rebates by Account","description":"Monthly allocation of Archera premiums, rebates, and savings by cloud account."}}},"components":{"schemas":{"ArcheraPremiumsAndRebatesByAccountOutput":{"type":"object","properties":{"account_id":{"type":"string","description":"Cloud account identifier"},"account_name":{"type":"string","description":"Human-readable account name"},"archera_premiums":{"type":"number","description":"Archera premiums allocated to this account"},"rebates":{"type":"number","description":"Rebates allocated to this account"},"gross_savings":{"type":"number","description":"Gross savings allocated to this account"},"net_savings":{"type":"number","description":"Net savings allocated to this account"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Archera Premiums and Rebates Daily

> Daily allocation of Archera premiums, rebates, and savings over a calendar month.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"reports","description":"Report download operations"}],"paths":{"/beta/v1/org/{org_id}/reports/archera_premiums_and_rebates_daily":{"get":{"parameters":[{"in":"query","name":"format","description":"Response format: 'json' (default) or 'csv'","schema":{"type":"string","default":"json","enum":["json","csv"]},"required":false},{"in":"query","name":"year","description":"Billing year (e.g. 2026)","schema":{"type":"integer"},"required":true},{"in":"query","name":"month","description":"Billing month (1-12)","schema":{"type":"integer","minimum":1,"maximum":12},"required":true},{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp, unknown)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ArcheraPremiumsAndRebatesDailyOutput"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["reports"],"summary":"Archera Premiums and Rebates Daily","description":"Daily allocation of Archera premiums, rebates, and savings over a calendar month."}}},"components":{"schemas":{"ArcheraPremiumsAndRebatesDailyOutput":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Calendar date within the requested month"},"gross_savings":{"type":"number","description":"Gross savings allocated to this date"},"archera_premiums":{"type":"number","description":"Archera premiums allocated to this date"},"rebates":{"type":"number","description":"Rebates allocated to this date"},"net_savings":{"type":"number","description":"Net savings allocated to this date"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Archera Premiums and Rebates by Account Daily

> Daily allocation of Archera premiums, rebates, and savings by cloud account over a calendar month.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"reports","description":"Report download operations"}],"paths":{"/beta/v1/org/{org_id}/reports/archera_premiums_and_rebates_by_account_daily":{"get":{"parameters":[{"in":"query","name":"format","description":"Response format: 'json' (default) or 'csv'","schema":{"type":"string","default":"json","enum":["json","csv"]},"required":false},{"in":"query","name":"year","description":"Billing year (e.g. 2026)","schema":{"type":"integer"},"required":true},{"in":"query","name":"month","description":"Billing month (1-12)","schema":{"type":"integer","minimum":1,"maximum":12},"required":true},{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp, unknown)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ArcheraPremiumsAndRebatesByAccountDailyOutput"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["reports"],"summary":"Archera Premiums and Rebates by Account Daily","description":"Daily allocation of Archera premiums, rebates, and savings by cloud account over a calendar month."}}},"components":{"schemas":{"ArcheraPremiumsAndRebatesByAccountDailyOutput":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Calendar date within the requested month"},"account_id":{"type":"string","description":"Cloud account identifier"},"account_name":{"type":"string","description":"Human-readable account name"},"gross_savings":{"type":"number","description":"Gross savings allocated to this account on this date"},"archera_premiums":{"type":"number","description":"Archera premiums allocated to this account on this date"},"rebates":{"type":"number","description":"Rebates allocated to this account on this date"},"net_savings":{"type":"number","description":"Net savings allocated to this account on this date"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Allocation Reports (Beta)

Calendar-month tabular breakdowns that spread Archera premiums, rebates, savings, and commitment costs across accounts, services, or child orgs.

## List available allocation reports

> Catalog of allocation/showback reports a caller can fetch via \`GET /allocation-reports/\<report\_type>\`. Each entry declares the query parameters it accepts and the columns its rows will contain.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Allocation Reports (Beta)","description":"Calendar-month tabular breakdowns that spread Archera premiums, rebates, savings, and commitment costs across accounts, services, or child orgs."}],"paths":{"/beta/v1/org/{org_id}/allocation-reports":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AllocationReportDescriptor"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Allocation Reports (Beta)"],"summary":"List available allocation reports","description":"Catalog of allocation/showback reports a caller can fetch via `GET /allocation-reports/<report_type>`. Each entry declares the query parameters it accepts and the columns its rows will contain."}}},"components":{"schemas":{"AllocationReportDescriptor":{"type":"object","properties":{"report_type":{"type":"string","description":"Identifier used as the path segment on the get endpoint (`/allocation-reports/<report_type>`)."},"name":{"type":"string","description":"Human-readable report title."},"description":{"type":"string","description":"What the report contains."},"category":{"type":"string","description":"Allocation tier. 'premiums_and_rebates' = Archera-side overlay only. 'commitment' = commitment cost redistributed from holding to usage accounts (typically with overlay alongside). 'cloud_bill' = full cloud bill including commitment + on-demand + Archera adjustments."},"row_grain":{"type":"string","description":"Time grain each row represents: 'monthly' (one row per calendar month, usually paired with another dim) or 'daily' (one row per calendar date)."},"update_cadence":{"type":"string","description":"When the report's underlying data changes. 'daily' = refreshes each day as new utilization lands; current-period previews are available and freeze after the period's invoice closes. 'on_period_close' = single snapshot when the invoice generates; calling for the current period returns empty until close. 'static' = never changes."},"params":{"type":"array","description":"Query parameters this report accepts.","items":{"$ref":"#/components/schemas/AllocationReportParamDescriptor"}},"output_fields":{"type":"array","description":"Columns each row of the report contains.","items":{"$ref":"#/components/schemas/AllocationReportFieldDescriptor"}}},"additionalProperties":false},"AllocationReportParamDescriptor":{"type":"object","properties":{"name":{"type":"string","description":"Query parameter name."},"type":{"type":"string","description":"JSON type: 'integer', 'number', 'string', or 'boolean'."},"required":{"type":"boolean","description":"Whether the parameter must be supplied."},"description":{"type":"string","description":"What the parameter controls."}},"additionalProperties":false},"AllocationReportFieldDescriptor":{"type":"object","properties":{"name":{"type":"string","description":"Output column name (snake_case in JSON)."},"type":{"type":"string","description":"JSON type of the column value."},"description":{"type":"string","description":"What the column represents."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Fetch one allocation report

> Returns one report's rows for the requested calendar month. Accepted query parameters and returned columns vary by \`report\_type\` — call the list endpoint to discover them. Pass \`?format=csv\` for a CSV download (default is JSON). Returns 404 for unknown or per-org-hidden reports, and 404 with \`code: period\_not\_available\` when the requested (year, month) isn't in this report's available periods — call the /periods endpoint to enumerate what is. marshmallow\.ValidationError on bad query params is handled globally as a 400.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Allocation Reports (Beta)","description":"Calendar-month tabular breakdowns that spread Archera premiums, rebates, savings, and commitment costs across accounts, services, or child orgs."}],"paths":{"/beta/v1/org/{org_id}/allocation-reports/{report_type}":{"get":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Allocation Reports (Beta)"],"summary":"Fetch one allocation report","description":"Returns one report's rows for the requested calendar month. Accepted query parameters and returned columns vary by `report_type` — call the list endpoint to discover them. Pass `?format=csv` for a CSV download (default is JSON). Returns 404 for unknown or per-org-hidden reports, and 404 with `code: period_not_available` when the requested (year, month) isn't in this report's available periods — call the /periods endpoint to enumerate what is. marshmallow.ValidationError on bad query params is handled globally as a 400."}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## List periods available for an allocation report

> Returns the (year, month) periods this report can be queried for, given the supplied filter params (same shape as the get endpoint minus year/month — those are the dimensions being enumerated). Each entry has \`status: "finalized"\` for past months backed by an invoice, or \`"in\_progress"\` for the current calendar month when the report's update\_cadence is "daily". Sorted most-recent first.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Allocation Reports (Beta)","description":"Calendar-month tabular breakdowns that spread Archera premiums, rebates, savings, and commitment costs across accounts, services, or child orgs."}],"paths":{"/beta/v1/org/{org_id}/allocation-reports/{report_type}/periods":{"get":{"responses":{"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Allocation Reports (Beta)"],"summary":"List periods available for an allocation report","description":"Returns the (year, month) periods this report can be queried for, given the supplied filter params (same shape as the get endpoint minus year/month — those are the dimensions being enumerated). Each entry has `status: \"finalized\"` for past months backed by an invoice, or `\"in_progress\"` for the current calendar month when the report's update_cadence is \"daily\". Sorted most-recent first."}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Commitment Plans (Beta)

Agent-friendly commitment plan endpoints

## List commitment plans

> Returns commitment plans scoped to one segment for the given provider. \`segment\_id\` defaults to the provider-resources segment — same fallback as POST/PUT — so the typical caller sees the plans tied to their default segment without cross-segment duplicates. Further filters (template, status, flags) narrow within that scope. Coverage metrics (current\_coverage / projected\_coverage) are omitted here for speed; fetch the detail endpoint for those.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"segment_id","description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false},{"in":"query","name":"template_id","description":"Filter to plans generated from this template (GET /commitment-plan-templates)","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false},{"in":"query","name":"status","description":"Filter by plan status (e.g. 'draft', 'in_progress')","schema":{"default":null,"type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress",null],"nullable":true},"required":false},{"in":"query","name":"is_recommended","description":"Filter to the flagged recommended plan","schema":{"type":"boolean","default":null,"nullable":true},"required":false},{"in":"query","name":"is_system_generated","description":"Filter to system-generated (default) plans — the three built-ins (Recommended / Balanced / High Savings) vs. user-created plans.","schema":{"type":"boolean","default":null,"nullable":true},"required":false},{"in":"query","name":"is_renewal","description":"Switch which flavor the list returns. Omitted (default) and false both return segment-scoped non-renewal plans — backward-compatible with the pre-renewal contract. Set to true to fetch renewal plans (which aren't segment-scoped — `segment_id` is ignored). There's no combined view; renewals and non-renewals are queried separately.","schema":{"type":"boolean","default":null,"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommitmentPlanList"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans (Beta)"],"summary":"List commitment plans","description":"Returns commitment plans scoped to one segment for the given provider. `segment_id` defaults to the provider-resources segment — same fallback as POST/PUT — so the typical caller sees the plans tied to their default segment without cross-segment duplicates. Further filters (template, status, flags) narrow within that scope. Coverage metrics (current_coverage / projected_coverage) are omitted here for speed; fetch the detail endpoint for those."}}},"components":{"schemas":{"CommitmentPlanList":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]}},"required":["created_at","id","is_calculating","is_renewal","max_term","minimum_commitment","name","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Create a commitment plan

> Creates a new commitment plan for the given segment. The plan is generated asynchronously; the response echoes the initial plan with is\_calculating=true and omits coverage fields (meaningless mid-recalc). Poll GET /commitment-plans/{plan\_id} once is\_calculating=false to get the full detail including coverage and per-service breakdowns.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlanList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommitmentPlanArgs"}}}},"tags":["Commitment Plans (Beta)"],"summary":"Create a commitment plan","description":"Creates a new commitment plan for the given segment. The plan is generated asynchronously; the response echoes the initial plan with is_calculating=true and omits coverage fields (meaningless mid-recalc). Poll GET /commitment-plans/{plan_id} once is_calculating=false to get the full detail including coverage and per-service breakdowns."}}},"components":{"schemas":{"CommitmentPlanList":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]}},"required":["created_at","id","is_calculating","is_renewal","max_term","minimum_commitment","name","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"CreateCommitmentPlanArgs":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"segment_id":{"type":"string","format":"uuid","default":null,"description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","nullable":true},"name":{"type":"string","description":"Human-readable plan name"},"configuration":{"description":"Inputs that drive plan generation","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]}},"required":["configuration","name","provider"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Create a renewal commitment plan

> Creates a new commitment plan that renews a set of expiring commitments. The plan covers the same resources the source commitments were covering, with the contract specs supplied in \`configuration\` driving the renewal recommendation. The plan is generated asynchronously — the response echoes the initial plan with \`is\_calculating=true\`; poll GET /commitment-plans/{plan\_id} until that flips to see the generated line items.\
> \
> Renewal plans always sit on the provider-resources segment; \`segment\_id\` is not accepted. The usage window the recommender feeds on is derived automatically from the source commitments' end dates, so \`configuration.lookback\_days\` is omitted (the field is rejected if sent). \`configuration.resource\_ids\` is also rejected — \`configuration.renewal\_commitment\_ids\` carries the scope for a renewal plan, parallel to how \`configuration.resource\_ids\` scopes an infrastructure plan on the regular create endpoint.\
> \
> Each generated line item carries a \`renewal\_commitment\_id\` linking it back to the source commitment it is proposed to replace. Pair with GET /commitment-plans/{plan\_id}/renewal-commitments to see the source commitments side-by-side.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/renewals":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlanList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRenewalCommitmentPlanArgs"}}}},"tags":["Commitment Plans (Beta)"],"summary":"Create a renewal commitment plan","description":"Creates a new commitment plan that renews a set of expiring commitments. The plan covers the same resources the source commitments were covering, with the contract specs supplied in `configuration` driving the renewal recommendation. The plan is generated asynchronously — the response echoes the initial plan with `is_calculating=true`; poll GET /commitment-plans/{plan_id} until that flips to see the generated line items.\n\nRenewal plans always sit on the provider-resources segment; `segment_id` is not accepted. The usage window the recommender feeds on is derived automatically from the source commitments' end dates, so `configuration.lookback_days` is omitted (the field is rejected if sent). `configuration.resource_ids` is also rejected — `configuration.renewal_commitment_ids` carries the scope for a renewal plan, parallel to how `configuration.resource_ids` scopes an infrastructure plan on the regular create endpoint.\n\nEach generated line item carries a `renewal_commitment_id` linking it back to the source commitment it is proposed to replace. Pair with GET /commitment-plans/{plan_id}/renewal-commitments to see the source commitments side-by-side."}}},"components":{"schemas":{"CommitmentPlanList":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]}},"required":["created_at","id","is_calculating","is_renewal","max_term","minimum_commitment","name","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"CreateRenewalCommitmentPlanArgs":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Human-readable plan name"},"configuration":{"description":"Inputs that drive plan generation, including the source `renewal_commitment_ids`. Renewal config omits `lookback_days` (derived from source commitments' end dates) and `resource_ids` (replaced by `renewal_commitment_ids` inside this same object).","allOf":[{"$ref":"#/components/schemas/RenewalCommitmentPlanConfiguration"}]}},"required":["configuration","name","provider"],"additionalProperties":false},"RenewalCommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating renewal line items. Each spec is a (commitment_type, contract_term, payment_option) triple — the recommender picks the best mix matching these specs against the expiring commitments' usage.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"renewal_commitment_ids":{"type":"array","minItems":1,"description":"Expiring commitment ids to renew. Required and non-empty. All ids must belong to the caller's org and the supplied provider, and each must have a non-null end_date (used to derive the usage-window for the renewal recommendation).","items":{"type":"string","format":"uuid"}}},"required":["contract_specs","renewal_commitment_ids"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get default commitment plans

> Returns the three default Archera commitment plans: Recommended (30-day), Balanced (1-year), and High Savings (3-year).

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/default":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"segment_id","description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommitmentPlan"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans (Beta)"],"summary":"Get default commitment plans","description":"Returns the three default Archera commitment plans: Recommended (30-day), Balanced (1-year), and High Savings (3-year)."}}},"components":{"schemas":{"CommitmentPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"current_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan."}},"required":["created_at","current_coverage","id","is_calculating","is_renewal","max_term","minimum_commitment","name","projected_coverage","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get recommended commitment plan

> Returns the single recommended commitment plan for the organization. This is typically the 30-day Recommended plan. Returns 204 if no plan is available.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/recommended":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"segment_id","description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlan"}}}},"204":{"description":"No Content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans (Beta)"],"summary":"Get recommended commitment plan","description":"Returns the single recommended commitment plan for the organization. This is typically the 30-day Recommended plan. Returns 204 if no plan is available."}}},"components":{"schemas":{"CommitmentPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"current_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan."}},"required":["created_at","current_coverage","id","is_calculating","is_renewal","max_term","minimum_commitment","name","projected_coverage","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get commitment plan details

> Returns details for a specific commitment plan by ID, including per-service breakdowns.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlanDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans (Beta)"],"summary":"Get commitment plan details","description":"Returns details for a specific commitment plan by ID, including per-service breakdowns."}}},"components":{"schemas":{"CommitmentPlanDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"current_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan."},"covered_services":{"type":"array","description":"List of cloud services covered by this plan, with per-service savings and commitment breakdowns","items":{"$ref":"#/components/schemas/CoveredService"}}},"required":["created_at","current_coverage","id","is_calculating","is_renewal","max_term","minimum_commitment","name","projected_coverage","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"CoveredService":{"type":"object","properties":{"service_name":{"type":"string","description":"Cloud service name (e.g. 'Amazon EC2', 'Amazon RDS')"},"num_commitments":{"type":"integer","description":"Number of individual commitments covering this service"},"current_coverage":{"type":"number","description":"Spend-based commitment coverage of this service's reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"Spend-based commitment coverage of this service's reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan."},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this service. cloud_provider_cost is `{total}` only (no recurring/amortized split at per-service level). commitment_savings has no rebate field on plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["current_coverage","num_commitments","projected_coverage","service_name"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Update a commitment plan

> Update the plan's name and/or configuration. Replacing \`configuration\` triggers a recalculation — the response will have is\_calculating=true and line-item financials are invalid until generation completes. Rejected if the plan is currently calculating, is a system-generated default, or is locked for purchase.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}":{"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlanList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCommitmentPlanArgs"}}}},"tags":["Commitment Plans (Beta)"],"summary":"Update a commitment plan","description":"Update the plan's name and/or configuration. Replacing `configuration` triggers a recalculation — the response will have is_calculating=true and line-item financials are invalid until generation completes. Rejected if the plan is currently calculating, is a system-generated default, or is locked for purchase."}}},"components":{"schemas":{"CommitmentPlanList":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]}},"required":["created_at","id","is_calculating","is_renewal","max_term","minimum_commitment","name","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"UpdateCommitmentPlanArgs":{"type":"object","properties":{"name":{"type":"string","description":"New plan name"},"configuration":{"description":"New plan configuration. Replacing this triggers a full regeneration of the plan's line items and financials. The plan's scope axis lives here too — `resource_ids` for infrastructure scope, `renewal_commitment_ids` for renewal scope (mutually exclusive). Sending the wrong scope field for the plan type is rejected; convert plan types by deleting and re-creating.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Delete a commitment plan

> Delete a commitment plan. Rejected if the plan is currently calculating, is a system-generated default, or is locked for purchase. Irreversible.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}":{"delete":{"responses":{"204":{"description":"No Content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans (Beta)"],"summary":"Delete a commitment plan","description":"Delete a commitment plan. Rejected if the plan is currently calculating, is a system-generated default, or is locked for purchase. Irreversible."}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Apply (purchase) a commitment plan

> Executes the plan's selected line items as actual commitment purchases. Marks the plan as edited and records the initiating user. The plan is then processed by the commitment-purchase workflow — inspect the plan status afterwards for progress. Rejected if the plan is currently calculating or already locked.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}/apply":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlanDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans (Beta)"],"summary":"Apply (purchase) a commitment plan","description":"Executes the plan's selected line items as actual commitment purchases. Marks the plan as edited and records the initiating user. The plan is then processed by the commitment-purchase workflow — inspect the plan status afterwards for progress. Rejected if the plan is currently calculating or already locked."}}},"components":{"schemas":{"CommitmentPlanDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"current_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan."},"covered_services":{"type":"array","description":"List of cloud services covered by this plan, with per-service savings and commitment breakdowns","items":{"$ref":"#/components/schemas/CoveredService"}}},"required":["created_at","current_coverage","id","is_calculating","is_renewal","max_term","minimum_commitment","name","projected_coverage","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"CoveredService":{"type":"object","properties":{"service_name":{"type":"string","description":"Cloud service name (e.g. 'Amazon EC2', 'Amazon RDS')"},"num_commitments":{"type":"integer","description":"Number of individual commitments covering this service"},"current_coverage":{"type":"number","description":"Spend-based commitment coverage of this service's reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"Spend-based commitment coverage of this service's reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan."},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this service. cloud_provider_cost is `{total}` only (no recurring/amortized split at per-service level). commitment_savings has no rebate field on plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["current_coverage","num_commitments","projected_coverage","service_name"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Copy a commitment plan, optionally applying line-item edits

> Creates a draft copy of an existing commitment plan, including its line items and resource matches. The copy is a regular user-created plan (is\_default=false, is\_recommended=false) and is editable via PUT /commitment-plans/{plan\_id}. Useful for forking a system-generated default plan (Recommended / Balanced / High Savings) so it can be modified — defaults themselves are read-only. The copy's status is always reset to draft, even when the source is scheduled, in progress, or completed, so copying cannot queue or execute a purchase. The copy inherits the source plan's already-computed line items and financials, so it is ready immediately (is\_calculating=false).\
> \
> Optionally apply line-item edits during the copy via two mutually exclusive modes:\
> \
> \- Explicit: pass \`line\_item\_updates\` referencing the SOURCE plan's line\_item\_ids; the server translates them to the copy's new IDs internally and applies them atomically.\
> \- Resolution: pass \`target\_contract\_term\` (+ optional \`target\_payment\_option\` / \`target\_line\_item\_ids\`) and the server swaps every selected (or scoped) line item on the copy to the closest candidate at or below the target term. Saves the LLM having to enumerate per-line edits when the user wants a uniform shape change on the new plan.\
> \
> If any edit fails (unknown source line\_item\_id, invalid offer, integer-coercion error on a unit-basis offer's \`selected\_amount\`, duplicate line\_item\_id within \`line\_item\_updates\`), the entire copy + updates rolls back — no orphan copy persists. This is the canonical 'copy to edit' workflow; saves the round trip and ID-translation logic vs a separate copy + update sequence.\
> \
> Returns the new plan in CommitmentPlanListSchema shape — id + headline financials + configuration; covered\_services and coverage fields are intentionally omitted because computing them eagerly loads per-service summaries (expensive) and the typical caller just needs the post-edit totals to confirm the copy. Follow up with \`commitment\_plan\_details\` on the returned id if you need the full breakdown. In resolution mode the response additionally carries a \`resolution\` array with one entry per scoped line item (\`actual\_term\` / \`actual\_payment\_option\` / \`actual\_term\_reason\` of \`exact\_match\`, \`fallback\_closest\_shorter\`, or \`no\_alternative\`). Surface no\_alternative outcomes to the user so they understand why coverage may be partial.\
> \
> Rejected if the source plan is currently being calculated.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}/copy":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLineItemUpdateResponse"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyCommitmentPlanArgs"}}}},"tags":["Commitment Plans (Beta)"],"summary":"Copy a commitment plan, optionally applying line-item edits","description":"Creates a draft copy of an existing commitment plan, including its line items and resource matches. The copy is a regular user-created plan (is_default=false, is_recommended=false) and is editable via PUT /commitment-plans/{plan_id}. Useful for forking a system-generated default plan (Recommended / Balanced / High Savings) so it can be modified — defaults themselves are read-only. The copy's status is always reset to draft, even when the source is scheduled, in progress, or completed, so copying cannot queue or execute a purchase. The copy inherits the source plan's already-computed line items and financials, so it is ready immediately (is_calculating=false).\n\nOptionally apply line-item edits during the copy via two mutually exclusive modes:\n\n- Explicit: pass `line_item_updates` referencing the SOURCE plan's line_item_ids; the server translates them to the copy's new IDs internally and applies them atomically.\n- Resolution: pass `target_contract_term` (+ optional `target_payment_option` / `target_line_item_ids`) and the server swaps every selected (or scoped) line item on the copy to the closest candidate at or below the target term. Saves the LLM having to enumerate per-line edits when the user wants a uniform shape change on the new plan.\n\nIf any edit fails (unknown source line_item_id, invalid offer, integer-coercion error on a unit-basis offer's `selected_amount`, duplicate line_item_id within `line_item_updates`), the entire copy + updates rolls back — no orphan copy persists. This is the canonical 'copy to edit' workflow; saves the round trip and ID-translation logic vs a separate copy + update sequence.\n\nReturns the new plan in CommitmentPlanListSchema shape — id + headline financials + configuration; covered_services and coverage fields are intentionally omitted because computing them eagerly loads per-service summaries (expensive) and the typical caller just needs the post-edit totals to confirm the copy. Follow up with `commitment_plan_details` on the returned id if you need the full breakdown. In resolution mode the response additionally carries a `resolution` array with one entry per scoped line item (`actual_term` / `actual_payment_option` / `actual_term_reason` of `exact_match`, `fallback_closest_shorter`, or `no_alternative`). Surface no_alternative outcomes to the user so they understand why coverage may be partial.\n\nRejected if the source plan is currently being calculated."}}},"components":{"schemas":{"PlanLineItemUpdateResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"resolution":{"type":"array","description":"Per-line-item resolution outcome when `target_contract_term` was passed. One entry per line item that was IN SCOPE for the request (covers `no_alternative` items too — those are not in the applied updates but are surfaced here so callers can see what the server couldn't satisfy). `actual_term_reason` is one of: `exact_match` (landed at target), `fallback_closest_shorter` (used the longest available term ≤ target with same payment option), `no_alternative` (no candidate satisfied — line item left unchanged). Absent / null on explicit-mode calls.","items":{"$ref":"#/components/schemas/HypotheticalLineItem"},"nullable":true}},"required":["created_at","id","is_calculating","is_renewal","max_term","minimum_commitment","name","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"HypotheticalLineItem":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"actual_term":{"description":"The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."}},"required":["actual_payment_option","actual_term","actual_term_reason","line_item_id"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"CopyCommitmentPlanArgs":{"type":"object","properties":{"target_contract_term":{"default":null,"description":"Server-side resolution mode. Set to a target contract term and the server resolves the per-line-item update set using the same fallback rule the comparison endpoint projects: exact match on (term, payment) where available, else closest shorter term with the same payment option (GRI preferred within tier). Mutually exclusive with explicit per-line-item updates — pass one OR the other, not both. Preferred over enumerating updates manually because the server can't silently omit entries from a list it builds itself.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"target_payment_option":{"default":"no_upfront","description":"Target payment option for resolution mode. Defaults to no_upfront — most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Ignored when `target_contract_term` is null.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"target_line_item_ids":{"type":"array","default":null,"description":"Optional subset of line items to update under resolution mode. If omitted, applies to all selected line items in the plan. Ignored when `target_contract_term` is null.","items":{"type":"string","format":"uuid"},"nullable":true},"name":{"type":"string","default":null,"description":"Name for the copied plan. If omitted, defaults to '<source plan name> <today's date>'.","nullable":true},"line_item_updates":{"type":"array","default":null,"description":"Optional list of line-item edits to apply during the copy. Each entry has the same shape as `update_commitment_plan_line_items`'s `updates` (line_item_id + optional is_selected / account_id / offer-swap triple). Entries reference the SOURCE plan's line_item_ids; the server translates them to the copy's new IDs internally and applies them atomically. If any edit fails, the entire copy + updates rolls back. Use this for the canonical 'copy to edit' workflow — saves the round trip and ID-translation logic that would otherwise live on the client. Mutually exclusive with `target_contract_term` (resolution mode).","items":{"$ref":"#/components/schemas/LineItemUpdateEntry"},"nullable":true}},"additionalProperties":false},"LineItemUpdateEntry":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"ID of the line item to update."},"is_selected":{"type":"boolean","description":"Include this line item in the plan's top-level financials and apply it when the plan is purchased."},"account_id":{"type":"string","description":"Cloud account ID this commitment is scoped to.","nullable":true},"offer_id":{"type":"string","format":"uuid","description":"Swap this line item's offer. Pair with `lease_menu_item_id` and `selected_amount` from the same comparison entry."},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to the chosen offer. Must come from the same comparison entry as `offer_id`. NULL VS OMITTED MATTERS: explicitly passing `null` clears the existing lease (converting a leased Archera-guaranteed commitment into a native one); omitting the field leaves the existing lease in place. To switch a leased GRI line item to a native offer, you MUST pass `null` here — otherwise the old lease stays attached and the line item's effective `contract_term` (derived from the lease's lockin hours) won't change.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount for the offer — unit count for RIs / unit-based CUDs, dollar-basis for Savings Plans / spend-based CUDs."}},"required":["line_item_id"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get commitment plan line items

> Returns individual commitment recommendations within a plan, including offer details, per-line-item savings, and costs. Each line item has an is\_selected field: if false, the line item is excluded from the plan and its costs/savings are NOT included in the plan's top-level metrics. Pass \`line\_item\_ids\` to fetch a specific subset (e.g. a single line item).

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items":{"get":{"parameters":[{"in":"query","name":"line_item_ids","description":"Optional list of line-item ids to scope the response to. When omitted, returns every line item in the plan.","schema":{"type":"array","default":null,"items":{"type":"string","format":"uuid"},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"renewal_commitment_ids","description":"Renewal plans only: scope to line items proposed as the replacement for these specific expiring commitments. Useful for \"show me what's being proposed to replace commitment X.\" Rejected with 400 on non-renewal plans (their line items have no renewal linkage; this guards against stale/wrong plan ids silently returning unrelated rows).","schema":{"type":"array","default":null,"items":{"type":"string","format":"uuid"},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"order_by","description":"Field to order results by","schema":{"type":"string","default":"monthly_net_savings","enum":["monthly_net_savings","monthly_total_cost","breakeven_days","discount_rate","upfront_cost"]},"required":false},{"in":"query","name":"desc","description":"Sort descending (default true)","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":20,"minimum":1,"maximum":10000},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommitmentLineItem"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans (Beta)"],"summary":"Get commitment plan line items","description":"Returns individual commitment recommendations within a plan, including offer details, per-line-item savings, and costs. Each line item has an is_selected field: if false, the line item is excluded from the plan and its costs/savings are NOT included in the plan's top-level metrics. Pass `line_item_ids` to fetch a specific subset (e.g. a single line item)."}}},"components":{"schemas":{"CommitmentLineItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Line item identifier"},"is_selected":{"type":"boolean","description":"Whether this line item is included in the plan. If false, this line item is excluded and its costs/savings are NOT reflected in the plan's top-level metrics."},"account_id":{"type":"string","description":"Cloud account ID this commitment applies to","nullable":true},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"contract_spec":{"description":"Detailed contract specifications including commitment type and properties","allOf":[{"$ref":"#/components/schemas/ContractSpec"}]},"offer":{"description":"Commitment offer details including type, region, and instance info","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1)"},"breakeven_days":{"readOnly":true,"description":"Days until this line item pays for itself"},"selected_amount":{"readOnly":true,"description":"Selected commitment amount — either a quantity (for RIs) or a dollar commitment (for Savings Plans), whichever is applicable"},"recommended_amount":{"readOnly":true,"description":"Recommended commitment amount — either a quantity (for RIs) or a dollar commitment (for Savings Plans), whichever is applicable"},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing for this specific line item. NOT a rate — do not sum with monthly-rate fields. Summing the commitment_upfront_cost of all selected line items equals the parent plan's commitment_upfront_cost."},"commitment_financials_monthly_rate":{"description":"Projected line item economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field on plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"covered_services":{"type":"array","description":"Cloud service identifiers (e.g. 'AmazonEC2', 'AmazonRDS') that this line item's commitment is expected to cover. Reflects the underlying resources the recommender matched to this commitment, not the offer's raw eligibility.","items":{"type":"string"}},"renewal_commitment_id":{"type":"string","format":"uuid","description":"ID of the expiring commitment this line item is renewing. Populated only on renewal plans (`plan_type=renewal`); null on purchase / infrastructure plans. Use the `renewal_commitment_ids` query param on this endpoint to filter to the line items proposed as replacements for specific expiring commitments.","nullable":true}},"required":["id","is_selected"],"additionalProperties":false},"ContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier"},"properties":{"type":"object","default":{},"description":"Additional contract properties","additionalProperties":{}},"term":{"description":"Contract term","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Payment option","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true}},"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Update commitment plan line items

> Atomically apply line-item edits in a single request. Two modes:\
> \
> \- Explicit: pass \`updates\`, a list where each entry carries the same fields the singular line-item update would accept (selection, account, offer-swap triple) plus the \`line\_item\_id\` selector.\
> \- Resolution: pass \`target\_contract\_term\` (+ optional \`target\_payment\_option\` / \`target\_line\_item\_ids\`) and the server swaps every selected (or scoped) line item to the closest candidate at or below the target term. Saves the LLM having to enumerate many edits when the user wants a uniform shape change.\
> \
> Modes are mutually exclusive. All updates are applied within a single transaction — if any fails (unknown line item, invalid offer, integer-coercion error on a unit-basis offer's \`selected\_amount\`), the whole call is rejected and no changes persist.\
> \
> Returns the updated plan in CommitmentPlanListSchema shape — id + headline financials + configuration; covered\_services and coverage fields are intentionally omitted because computing them eagerly loads per-service summaries (expensive) and the typical caller just needs the post-edit totals to confirm the change. Follow up with \`commitment\_plan\_details\` on the returned id if you need the full breakdown. In resolution mode the response additionally carries a \`resolution\` array with one entry per scoped line item: the \`actual\_term\` / \`actual\_payment\_option\` applied and an \`actual\_term\_reason\` of \`exact\_match\`, \`fallback\_closest\_shorter\`, or \`no\_alternative\` (the latter were left untouched). Surface no\_alternative outcomes to the user so they understand why coverage may be partial.\
> \
> Rejected if the parent plan is currently calculating, is a system-generated default, or is locked for purchase.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items/update":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanLineItemUpdateResponse"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLineItemsArgs"}}}},"tags":["Commitment Plans (Beta)"],"summary":"Update commitment plan line items","description":"Atomically apply line-item edits in a single request. Two modes:\n\n- Explicit: pass `updates`, a list where each entry carries the same fields the singular line-item update would accept (selection, account, offer-swap triple) plus the `line_item_id` selector.\n- Resolution: pass `target_contract_term` (+ optional `target_payment_option` / `target_line_item_ids`) and the server swaps every selected (or scoped) line item to the closest candidate at or below the target term. Saves the LLM having to enumerate many edits when the user wants a uniform shape change.\n\nModes are mutually exclusive. All updates are applied within a single transaction — if any fails (unknown line item, invalid offer, integer-coercion error on a unit-basis offer's `selected_amount`), the whole call is rejected and no changes persist.\n\nReturns the updated plan in CommitmentPlanListSchema shape — id + headline financials + configuration; covered_services and coverage fields are intentionally omitted because computing them eagerly loads per-service summaries (expensive) and the typical caller just needs the post-edit totals to confirm the change. Follow up with `commitment_plan_details` on the returned id if you need the full breakdown. In resolution mode the response additionally carries a `resolution` array with one entry per scoped line item: the `actual_term` / `actual_payment_option` applied and an `actual_term_reason` of `exact_match`, `fallback_closest_shorter`, or `no_alternative` (the latter were left untouched). Surface no_alternative outcomes to the user so they understand why coverage may be partial.\n\nRejected if the parent plan is currently calculating, is a system-generated default, or is locked for purchase."}}},"components":{"schemas":{"PlanLineItemUpdateResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"resolution":{"type":"array","description":"Per-line-item resolution outcome when `target_contract_term` was passed. One entry per line item that was IN SCOPE for the request (covers `no_alternative` items too — those are not in the applied updates but are surfaced here so callers can see what the server couldn't satisfy). `actual_term_reason` is one of: `exact_match` (landed at target), `fallback_closest_shorter` (used the longest available term ≤ target with same payment option), `no_alternative` (no candidate satisfied — line item left unchanged). Absent / null on explicit-mode calls.","items":{"$ref":"#/components/schemas/HypotheticalLineItem"},"nullable":true}},"required":["created_at","id","is_calculating","is_renewal","max_term","minimum_commitment","name","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"HypotheticalLineItem":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"actual_term":{"description":"The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."}},"required":["actual_payment_option","actual_term","actual_term_reason","line_item_id"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"UpdateLineItemsArgs":{"type":"object","properties":{"target_contract_term":{"default":null,"description":"Server-side resolution mode. Set to a target contract term and the server resolves the per-line-item update set using the same fallback rule the comparison endpoint projects: exact match on (term, payment) where available, else closest shorter term with the same payment option (GRI preferred within tier). Mutually exclusive with explicit per-line-item updates — pass one OR the other, not both. Preferred over enumerating updates manually because the server can't silently omit entries from a list it builds itself.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"target_payment_option":{"default":"no_upfront","description":"Target payment option for resolution mode. Defaults to no_upfront — most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Ignored when `target_contract_term` is null.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"target_line_item_ids":{"type":"array","default":null,"description":"Optional subset of line items to update under resolution mode. If omitted, applies to all selected line items in the plan. Ignored when `target_contract_term` is null.","items":{"type":"string","format":"uuid"},"nullable":true},"updates":{"type":"array","default":null,"minItems":1,"description":"List of per-line-item updates to apply atomically. Required unless `target_contract_term` is set (resolution mode). Each entry's `line_item_id` must be on the parent plan.","items":{"$ref":"#/components/schemas/LineItemUpdateEntry"},"nullable":true}},"additionalProperties":false},"LineItemUpdateEntry":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"ID of the line item to update."},"is_selected":{"type":"boolean","description":"Include this line item in the plan's top-level financials and apply it when the plan is purchased."},"account_id":{"type":"string","description":"Cloud account ID this commitment is scoped to.","nullable":true},"offer_id":{"type":"string","format":"uuid","description":"Swap this line item's offer. Pair with `lease_menu_item_id` and `selected_amount` from the same comparison entry."},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to the chosen offer. Must come from the same comparison entry as `offer_id`. NULL VS OMITTED MATTERS: explicitly passing `null` clears the existing lease (converting a leased Archera-guaranteed commitment into a native one); omitting the field leaves the existing lease in place. To switch a leased GRI line item to a native offer, you MUST pass `null` here — otherwise the old lease stays attached and the line item's effective `contract_term` (derived from the lease's lockin hours) won't change.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount for the offer — unit count for RIs / unit-based CUDs, dollar-basis for Savings Plans / spend-based CUDs."}},"required":["line_item_id"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## List the commitments being renewed by a renewal plan

> Returns the expiring commitments that a renewal plan is proposed to replace — identity, dates, guarantee info, and contract term. Ordered by \`end\_date\` ascending (earliest-expiring first) so the caller surfaces the most-urgent renewals first.\
> \
> Rejected with 400 if the plan is not a renewal plan — for non-renewal plans use /line-items or /covered-resources instead.\
> \
> To filter to the commitments tied to a subset of line items, pass \`line\_item\_ids\`. To go the other direction (line items proposed as replacements for a given source commitment), use the \`renewal\_commitment\_ids\` filter on /line-items.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}/renewal-commitments":{"get":{"parameters":[{"in":"query","name":"line_item_ids","description":"Optional list of line-item ids to scope to. When supplied, returns only the source commitments whose renewing line items are in this set.","schema":{"type":"array","default":null,"items":{"type":"string","format":"uuid"},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":50,"minimum":1,"maximum":200},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Commitment"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans (Beta)"],"summary":"List the commitments being renewed by a renewal plan","description":"Returns the expiring commitments that a renewal plan is proposed to replace — identity, dates, guarantee info, and contract term. Ordered by `end_date` ascending (earliest-expiring first) so the caller surfaces the most-urgent renewals first.\n\nRejected with 400 if the plan is not a renewal plan — for non-renewal plans use /line-items or /covered-resources instead.\n\nTo filter to the commitments tied to a subset of line items, pass `line_item_ids`. To go the other direction (line items proposed as replacements for a given source commitment), use the `renewal_commitment_ids` filter on /line-items."}}},"components":{"schemas":{"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Compare commitment offers across a plan's line items

> Returns per-line-item offer alternatives plus plan-wide rollups for each (contract\_term, payment\_option) hypothetical. Designed to answer 'what would the plan look like at 3-year' in a single call: hypothetical\_totals carries the rolled-up financials and delta\_vs\_current, with per-line-item resolution exposed for transparency. Each line item lands at the target term when available, else the longest available term <= target with the same payment option (GRI preferred within tier), else its current term. Defaults: line\_item\_ids=all selected, contract\_terms=all distinct in candidates, payment\_options=\[no\_upfront].

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}/comparison":{"get":{"parameters":[{"in":"query","name":"line_item_ids","description":"Optional subset of line items to compare. If omitted, defaults to all selected line items in the plan.","schema":{"type":"array","default":null,"items":{"type":"string","format":"uuid"},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"contract_terms","description":"Optional list of target terms to roll up. If omitted, the response includes a hypothetical for every distinct contract_term that appears in any line item's candidates after the payment-option filter.","schema":{"type":"array","default":null,"items":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"payment_options","description":"Payment options to include. Defaults to no_upfront only — most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Pass partial_upfront / all_upfront explicitly to surface those.","schema":{"type":"array","items":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":false,"explode":true,"style":"form"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LineItemOfferComparisonResponse"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans (Beta)"],"summary":"Compare commitment offers across a plan's line items","description":"Returns per-line-item offer alternatives plus plan-wide rollups for each (contract_term, payment_option) hypothetical. Designed to answer 'what would the plan look like at 3-year' in a single call: hypothetical_totals carries the rolled-up financials and delta_vs_current, with per-line-item resolution exposed for transparency. Each line item lands at the target term when available, else the longest available term <= target with the same payment option (GRI preferred within tier), else its current term. Defaults: line_item_ids=all selected, contract_terms=all distinct in candidates, payment_options=[no_upfront]."}}},"components":{"schemas":{"LineItemOfferComparisonResponse":{"type":"object","properties":{"current_totals":{"description":"Plan-wide totals for the line items currently in scope (defaults to all selected, narrowed by line_item_ids if provided). Use this as the baseline when interpreting hypothetical deltas.","allOf":[{"$ref":"#/components/schemas/LineItemOfferComparisonTotals"}]},"hypothetical_totals":{"type":"array","description":"One entry per (contract_term, payment_option) combination requested (or per distinct term present in candidates if contract_terms was omitted). Each entry's totals + delta_vs_current answer 'what's the plan-wide impact of this term?' in one place — no client-side summing across line items required.","items":{"$ref":"#/components/schemas/HypotheticalTotal"}},"data":{"type":"array","description":"Per-line-item detail. Use when the user wants to drill into 'why does RDS not have a 3-year candidate' or to assemble an update payload.","items":{"$ref":"#/components/schemas/LineItemOfferComparisonRow"}}},"required":["current_totals","data","hypothetical_totals"],"additionalProperties":false},"LineItemOfferComparisonTotals":{"type":"object","properties":{"commitment_financials_monthly_rate":{"description":"730-hour monthly rate financials summed across the line items in scope. Same shape as on plans / line items.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars at signing across the line items in scope. NOT a rate — do not sum with monthly-rate fields."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"HypotheticalTotal":{"type":"object","properties":{"contract_term":{"description":"Target contract term for this hypothetical.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Target payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"description":"Rolled-up monthly-rate financials assuming each line item adopts its candidate per the fallback rule. Same shape as on plans / line items.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars across the line items under this hypothetical. NOT a rate."},"delta_vs_current":{"description":"Axis-by-axis difference vs current_totals. The headline 'should I do this' answer is delta_vs_current.monthly_net_savings.","allOf":[{"$ref":"#/components/schemas/HypotheticalDelta"}]},"line_items":{"type":"array","description":"Per-line-item resolution for this hypothetical. Use to call out fallbacks ('14 of 20 line items would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current').","items":{"$ref":"#/components/schemas/HypotheticalLineItem"}}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","line_items","payment_option"],"additionalProperties":false},"HypotheticalDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the plan does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"HypotheticalLineItem":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"actual_term":{"description":"The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."}},"required":["actual_payment_option","actual_term","actual_term_reason","line_item_id"],"additionalProperties":false},"LineItemOfferComparisonRow":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"current":{"description":"The line item's current offer + lease, in the same shape as OfferComparisonEntrySchema. Its delta_vs_current is all zeros.","allOf":[{"$ref":"#/components/schemas/OfferComparisonEntry"}]},"candidates":{"type":"array","description":"Alternative (offer, lease) pairs for this line item, filtered to the requested contract_terms and payment_options. Each entry carries its own contract_term and payment_option (on offer); fields offer_id, lease_menu_item_id, and selected_amount can be copied verbatim into POST /commitment-plans/{plan_id}/line-items/update (in the `updates` list) to swap the line item to that candidate.","items":{"$ref":"#/components/schemas/OfferComparisonEntry"}}},"required":["candidates","current","line_item_id"],"additionalProperties":false},"OfferComparisonEntry":{"type":"object","properties":{"is_current":{"type":"boolean","description":"True if this entry matches the line item's current offer + lease. Exactly one entry per response has this set; its `delta_vs_current` values are all zero."},"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost).","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","allOf":[{"$ref":"#/components/schemas/OfferComparisonDelta"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","is_current","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":"number","description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven.","nullable":true}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## List filterable covered-resource attributes for a plan

> Returns the fields that can be used in the \`filter\` parameter of /commitment-plans/\<plan\_id>/covered-resources, scoped to the resources the plan actually covers.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BaseAttribute"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"List filterable covered-resource attributes for a plan","tags":["Commitment Plans (Beta)"],"description":"Returns the fields that can be used in the `filter` parameter of /commitment-plans/<plan_id>/covered-resources, scoped to the resources the plan actually covers."}}},"components":{"schemas":{"BaseAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean","integer","float","date","datetime","time","currency","percent","string","enum","uuid","tags"]}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get valid values for a filterable covered-resource attribute

> Returns the distinct values for a given field, restricted to the resources the plan covers (and further narrowed by any search/filter passed). Use to discover valid filter values without paginating through the covered-resources list.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes/{field}":{"get":{"parameters":[{"in":"query","name":"line_item_ids","description":"Filter to matches from specific line items","schema":{"type":"array","default":null,"items":{"type":"string","format":"uuid"},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"only_selected_line_items","description":"Only include matches from selected line items (default true)","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"search","description":"Free-text ILIKE search across the resource SKU's identity and classification fields (resource id, name, account ids, service, region, instance_type, etc.). Mirrors the search lane on /resources/skus.","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — same {field, op, value} tree accepted by /resources/skus. Filterable on the resource SKU side: identity, tags (`has` with nested key/value filters), SKU classification, and the trailing-30-day spend/usage aggregates: `total_cost`, `ondemand_cost`, `gross_savings` (TOTAL summed over the trailing 30 days, NOT a monthly rate — same basis as /resources/skus), `coverage` (spend-based fraction covered by ALL existing commitments — current actuals, NOT this plan's projected coverage; that's the response's per-match `projected_coverage`), and `uptime` (fraction). All warehouse aggregates here are actuals across existing commitments, NOT plan-scoped projections. Call /covered-resources/attributes for the full filterable surface.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by. Defaults to monthly_net_savings. All numeric axes are 730-hour monthly rates on the per-match plan economics, net of the Archera premium where applicable (NOT the resource's warehouse trailing-30-day actuals — those are filterable but not orderable here, on purpose, to keep sort and response framing on the same monthly basis).","schema":{"type":"string","default":"monthly_net_savings","enum":["id","projected_coverage","monthly_net_savings","monthly_before_cost","monthly_after_cost","monthly_after_ondemand_cost"]},"required":false},{"in":"query","name":"desc","description":"Sort descending (default true)","schema":{"type":"boolean","default":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attribute"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Get valid values for a filterable covered-resource attribute","tags":["Commitment Plans (Beta)"],"description":"Returns the distinct values for a given field, restricted to the resources the plan covers (and further narrowed by any search/filter passed). Use to discover valid filter values without paginating through the covered-resources list."}}},"components":{"schemas":{"Attribute":{"oneOf":[{"$ref":"#/components/schemas/BooleanAttribute"},{"$ref":"#/components/schemas/UUIDAttribute"},{"$ref":"#/components/schemas/StringAttribute"},{"$ref":"#/components/schemas/IntegerAttribute"},{"$ref":"#/components/schemas/FloatAttribute"},{"$ref":"#/components/schemas/CurrencyAttribute"},{"$ref":"#/components/schemas/PercentAttribute"},{"$ref":"#/components/schemas/DateTimeAttribute"},{"$ref":"#/components/schemas/DateAttribute"},{"$ref":"#/components/schemas/TimeAttribute"},{"$ref":"#/components/schemas/EnumAttribute"},{"$ref":"#/components/schemas/TagsAttribute"}],"discriminator":{"propertyName":"type","mapping":{"boolean":"#/components/schemas/BooleanAttribute","uuid":"#/components/schemas/UUIDAttribute","string":"#/components/schemas/StringAttribute","integer":"#/components/schemas/IntegerAttribute","float":"#/components/schemas/FloatAttribute","currency":"#/components/schemas/CurrencyAttribute","percent":"#/components/schemas/PercentAttribute","datetime":"#/components/schemas/DateTimeAttribute","date":"#/components/schemas/DateAttribute","time":"#/components/schemas/TimeAttribute","enum":"#/components/schemas/EnumAttribute","tags":"#/components/schemas/TagsAttribute"}}},"BooleanAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false},"UUIDAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["uuid"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"StringAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["string"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"IntegerAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["integer"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"FloatAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["float"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"CurrencyAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["currency"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"PercentAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["percent"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateTimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["datetime"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["date"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"TimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["time"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"EnumAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["enum"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"TagsAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["tags"],"readOnly":true},"tags":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Aggregated covered-resources summary for a commitment plan

> Returns the resources a commitment plan covers, aggregated by (service, account, region, resource\_type). Each row is one group: rolled-up costs, savings, spend-weighted coverage, and resource count. Sorted by net savings descending. For per-resource detail, use the paginated /covered-resources endpoint.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/summary":{"get":{"parameters":[{"in":"query","name":"line_item_ids","description":"Filter to matches from specific line items","schema":{"type":"array","default":null,"items":{"type":"string","format":"uuid"},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"only_selected_line_items","description":"Only include matches from selected line items (default true)","schema":{"type":"boolean","default":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ResourceMatchSummary"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans (Beta)"],"summary":"Aggregated covered-resources summary for a commitment plan","description":"Returns the resources a commitment plan covers, aggregated by (service, account, region, resource_type). Each row is one group: rolled-up costs, savings, spend-weighted coverage, and resource count. Sorted by net savings descending. For per-resource detail, use the paginated /covered-resources endpoint."}}},"components":{"schemas":{"ResourceMatchSummary":{"type":"object","properties":{"service":{"type":"string","description":"Cloud service name (e.g. 'AmazonEC2', 'AmazonRDS')","nullable":true},"account_id":{"type":"string","description":"Cloud account ID","nullable":true},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"resource_type":{"type":"string","description":"Resource type within this group — instance family for compute (e.g. 'm5'), usage type for other services (e.g. 'Fargate-GB-Hours', 'Lambda-GB-Second'), or SKU name as fallback","nullable":true},"resource_count":{"type":"integer","description":"Number of resources in this group"},"projected_coverage":{"type":"number","description":"Spend-based projected coverage across resources in this group (0-1), weighted by each resource's on-demand-equivalent cost. Distinct from `resource.coverage` (trailing-30-day actual spend-based coverage from existing commitments). For per-resource projected coverage, use the paginated /covered-resources endpoint."},"commitment_financials_monthly_rate":{"description":"Plan economics scoped to this resource group, as 730-hour monthly rates. cloud_provider_cost has `{total}` only — per-group aggregates don't have the recurring/amortized_upfront split. commitment_savings has no rebate field on plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Paginated covered resources for a commitment plan

> Returns one row per resource the plan covers, with the plan's economics scoped to that resource (coverage, monthly savings, before/after cost) and full ResourceSKU detail. Supports search, structured filter, sort, and cursor pagination — same surface idiom as /resources/skus, but scoped to the plan's matched resources. Use /covered-resources/summary for the aggregated breakdown. \`X-Pagination\` is navigation-only: it always includes \`page\` and \`first\_page\`, and adds \`previous\_page\` and \`next\_page\` when available.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plans (Beta)","description":"Agent-friendly commitment plan endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources":{"get":{"parameters":[{"in":"query","name":"line_item_ids","description":"Filter to matches from specific line items","schema":{"type":"array","default":null,"items":{"type":"string","format":"uuid"},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"only_selected_line_items","description":"Only include matches from selected line items (default true)","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"search","description":"Free-text ILIKE search across the resource SKU's identity and classification fields (resource id, name, account ids, service, region, instance_type, etc.). Mirrors the search lane on /resources/skus.","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — same {field, op, value} tree accepted by /resources/skus. Filterable on the resource SKU side: identity, tags (`has` with nested key/value filters), SKU classification, and the trailing-30-day spend/usage aggregates: `total_cost`, `ondemand_cost`, `gross_savings` (TOTAL summed over the trailing 30 days, NOT a monthly rate — same basis as /resources/skus), `coverage` (spend-based fraction covered by ALL existing commitments — current actuals, NOT this plan's projected coverage; that's the response's per-match `projected_coverage`), and `uptime` (fraction). All warehouse aggregates here are actuals across existing commitments, NOT plan-scoped projections. Call /covered-resources/attributes for the full filterable surface.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by. Defaults to monthly_net_savings. All numeric axes are 730-hour monthly rates on the per-match plan economics, net of the Archera premium where applicable (NOT the resource's warehouse trailing-30-day actuals — those are filterable but not orderable here, on purpose, to keep sort and response framing on the same monthly basis).","schema":{"type":"string","default":"monthly_net_savings","enum":["id","projected_coverage","monthly_net_savings","monthly_before_cost","monthly_after_cost","monthly_after_ondemand_cost"]},"required":false},{"in":"query","name":"desc","description":"Sort descending (default true)","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ResourceMatchDetail"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plans (Beta)"],"summary":"Paginated covered resources for a commitment plan","description":"Returns one row per resource the plan covers, with the plan's economics scoped to that resource (coverage, monthly savings, before/after cost) and full ResourceSKU detail. Supports search, structured filter, sort, and cursor pagination — same surface idiom as /resources/skus, but scoped to the plan's matched resources. Use /covered-resources/summary for the aggregated breakdown. `X-Pagination` is navigation-only: it always includes `page` and `first_page`, and adds `previous_page` and `next_page` when available."}}},"components":{"schemas":{"ResourceMatchDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Match identifier — stable per (plan, line item, resource) tuple. For the resource's own id, see `resource.id`."},"line_item_id":{"type":"string","format":"uuid","description":"Parent line item ID"},"projected_coverage":{"type":"number","description":"Spend-based fraction of this resource's usage THIS plan would cover (0-1). At this single-price resource-match granularity, the usage-unit and spend ratios are equivalent. Distinct from `resource.coverage`, which is trailing-30-day actual spend-based coverage from existing commitments (the BEFORE picture). For the cost-weighted group rollup, see the /covered-resources/summary endpoint."},"commitment_financials_monthly_rate":{"description":"Plan economics scoped to this resource, as 730-hour monthly rates. cloud_provider_cost has `{total}` only — per-match data doesn't have the recurring/amortized_upfront split. commitment_savings has no rebate field on plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"resource":{"description":"Detailed resource information including provider, service, region, instance type, account, and other infrastructure details","anyOf":[{"$ref":"#/components/schemas/ResourceSKU"},{"type":"object","nullable":true}]}},"required":["resource"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"ResourceSKU":{"type":"object","properties":{"id":{"type":"string","description":"Composite ResourceSKU id — `<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`. Pass directly to `/resources/skus/<id>` for detail; do not parse it client-side."},"resource_id":{"type":"string","format":"uuid","description":"Underlying Resource id. Stable across SKU/time variants of the same resource — multiple ResourceSKU rows can share a `resource_id` when the same resource ran with different SKUs over its lifetime."},"catalog_sku_id":{"type":"string","format":"uuid","description":"Join key into `/catalog/skus/<id>` for the public SKU record."},"catalog_sku_org_id":{"type":"string","description":"Org id that owns the catalog SKU — public-catalog SKUs use the public org id; custom-priced SKUs use the customer's org id."},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"provider_resource_id":{"type":"string","description":"Provider's id for the resource (AWS ARN, Azure resource ID, GCP resource name). This is the canonical identifier the user sees in the cloud console."},"provider_sku_id":{"type":"string","description":"Provider's own SKU identifier","nullable":true},"name":{"type":"string","description":"Resource name (Resource.name) — the user-applied label, e.g. 'prod-db-1'. Distinct from `sku_name`, which is the catalog SKU's display name.","nullable":true},"sku_name":{"type":"string","description":"Catalog SKU display name (e.g. 'Amazon EC2 Instance', 'Amazon Aurora PostgreSQL Cluster'). Useful as a fallback label when `instance_type_family` and `usage_type` are both null. Distinct from `name` (the resource's user-applied label).","nullable":true},"integration_id":{"type":"string","description":"Integration this resource belongs to"},"billing_account_id":{"type":"string","description":"Provider billing/management account id","nullable":true},"sub_account_id":{"type":"string","description":"Provider account id that owns/created the resource","nullable":true},"resource_group":{"type":"string","nullable":true},"is_spot":{"type":"boolean","nullable":true},"availability_zone":{"type":"string","nullable":true},"service":{"type":"string","description":"Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')","nullable":true},"provider_service":{"type":"string","description":"Provider service code (e.g. 'AmazonEC2')","nullable":true},"family":{"type":"string","description":"Product family (e.g. 'Compute Instance')","nullable":true},"region_code":{"type":"string","description":"Region code (e.g. 'us-east-1')","nullable":true},"full_region_name":{"type":"string","description":"Full region name (e.g. 'US East (N. Virginia)')","nullable":true},"instance_type":{"type":"string","nullable":true},"instance_type_family":{"type":"string","nullable":true},"usage_type":{"type":"string","description":"Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items.","nullable":true},"operation":{"type":"string","description":"Provider billing operation code (e.g. 'RunInstances:0002')","nullable":true},"operating_system":{"type":"string","nullable":true},"tenancy":{"type":"string","nullable":true},"database_engine":{"type":"string","nullable":true},"database_edition":{"type":"string","nullable":true},"cache_engine":{"type":"string","nullable":true},"is_multi_az":{"type":"boolean","nullable":true},"is_current_generation":{"type":"boolean","nullable":true},"license_model":{"type":"string","nullable":true},"pre_installed_sw":{"type":"string","nullable":true},"processor_architecture":{"type":"string","nullable":true},"is_reservable":{"type":"boolean","description":"Whether the SKU this resource is running has at least one reserved-term offering. Reservability is a property of the SKU, not the resource.","nullable":true},"is_byol":{"type":"boolean","description":"Whether the SKU is a Bring-Your-Own-License variant. Currently set for AWS RDS BYOL only; false elsewhere.","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the SKU is eligible for instance-size flexibility under reserved offerings (provider+service-specific rules — see `is_flexible` on the ResourceSKU model).","nullable":true},"is_serverless":{"type":"boolean","description":"Whether the SKU represents serverless usage.","nullable":true},"vcpu":{"type":"number","nullable":true},"memory":{"type":"number","description":"Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.","nullable":true},"ondemand_usage_unit":{"type":"string","nullable":true},"ondemand_usage_price":{"type":"number","description":"On-demand unit price in `price_currency`. List price from the catalog — this is NOT the user's actual spend for this resource (see ResourceSKUWithMetricsSchema's `total_cost` or /cost-explorer for that).","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_start":{"type":"string","format":"date-time","description":"Start of the period during which the resource was observed running this SKU. A resource that switched SKUs (e.g. instance-type resize) will have multiple ResourceSKU rows with disjoint `[usage_start, usage_end]` windows."},"usage_end":{"type":"string","format":"date-time","description":"End of the period during which the resource was observed running this SKU. Within ~2 days of now generally indicates the resource is currently active with this SKU."},"tags":{"type":"object","description":"Merged provider + user tags (user tags take precedence). Empty when the resource has no tags. Use the `untagged` filter to find resources with no tags at all.","additionalProperties":{"type":"string"},"nullable":true}},"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Commitment Plan Templates (Beta)

Agent-friendly commitment plan template endpoints

## List commitment plan templates

> Returns commitment plan templates scoped to one segment for the given provider. \`segment\_id\` defaults to the provider-resources segment — same fallback as POST/PUT — so the typical caller sees exactly the templates tied to their default segment without cross-segment duplicates.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plan Templates (Beta)","description":"Agent-friendly commitment plan template endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plan-templates":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"segment_id","description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommitmentPlanTemplate"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plan Templates (Beta)"],"summary":"List commitment plan templates","description":"Returns commitment plan templates scoped to one segment for the given provider. `segment_id` defaults to the provider-resources segment — same fallback as POST/PUT — so the typical caller sees exactly the templates tied to their default segment without cross-segment duplicates."}}},"components":{"schemas":{"CommitmentPlanTemplate":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique template identifier"},"name":{"type":"string","description":"Human-readable template name"},"segment_id":{"type":"string","format":"uuid","description":"Segment this template generates plans for"},"created_at":{"type":"string","format":"date-time","description":"When the template was created"},"is_system_generated":{"type":"boolean","description":"True if this template was created automatically by the system — the three built-ins that back Recommended / Balanced / High Savings. Describes origin, not role — system-generated templates are immutable."},"configuration":{"description":"The inputs that plans generated from this template will use","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"auto_purchase":{"description":"Scheduled auto-purchase settings, or null if the template is not on a schedule.","anyOf":[{"$ref":"#/components/schemas/AutoPurchase"},{"type":"object","nullable":true}]}},"required":["auto_purchase","configuration","created_at","id","is_system_generated","name","segment_id"],"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"AutoPurchase":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the schedule is currently active"},"schedule":{"type":"string","enum":["daily","weekly","monthly"],"description":"Cadence: 'daily', 'weekly', or 'monthly'"},"min_monthly_savings":{"type":"number","description":"Dollar floor on projected monthly savings — plans that don't clear this are skipped even when the schedule fires."},"start_date":{"type":"string","format":"date","description":"Earliest date the automation may fire (inclusive). Null = no lower bound.","nullable":true},"end_date":{"type":"string","format":"date","description":"Latest date the automation may fire (inclusive). Null = no upper bound.","nullable":true},"next_execution_date":{"type":"string","format":"date","description":"When the next automated run is scheduled (computed)"},"last_executed_at":{"type":"string","format":"date-time","description":"When the last automated run fired, or null if it has not yet","nullable":true}},"required":["enabled","end_date","min_monthly_savings","schedule","start_date"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Create a commitment plan template

> Creates a reusable commitment plan template. If \`auto\_purchase\` is provided, the system will regenerate and optionally purchase plans from this template on the given schedule.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plan Templates (Beta)","description":"Agent-friendly commitment plan template endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plan-templates":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlanTemplate"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommitmentPlanTemplateArgs"}}}},"tags":["Commitment Plan Templates (Beta)"],"summary":"Create a commitment plan template","description":"Creates a reusable commitment plan template. If `auto_purchase` is provided, the system will regenerate and optionally purchase plans from this template on the given schedule."}}},"components":{"schemas":{"CommitmentPlanTemplate":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique template identifier"},"name":{"type":"string","description":"Human-readable template name"},"segment_id":{"type":"string","format":"uuid","description":"Segment this template generates plans for"},"created_at":{"type":"string","format":"date-time","description":"When the template was created"},"is_system_generated":{"type":"boolean","description":"True if this template was created automatically by the system — the three built-ins that back Recommended / Balanced / High Savings. Describes origin, not role — system-generated templates are immutable."},"configuration":{"description":"The inputs that plans generated from this template will use","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"auto_purchase":{"description":"Scheduled auto-purchase settings, or null if the template is not on a schedule.","anyOf":[{"$ref":"#/components/schemas/AutoPurchase"},{"type":"object","nullable":true}]}},"required":["auto_purchase","configuration","created_at","id","is_system_generated","name","segment_id"],"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"AutoPurchase":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the schedule is currently active"},"schedule":{"type":"string","enum":["daily","weekly","monthly"],"description":"Cadence: 'daily', 'weekly', or 'monthly'"},"min_monthly_savings":{"type":"number","description":"Dollar floor on projected monthly savings — plans that don't clear this are skipped even when the schedule fires."},"start_date":{"type":"string","format":"date","description":"Earliest date the automation may fire (inclusive). Null = no lower bound.","nullable":true},"end_date":{"type":"string","format":"date","description":"Latest date the automation may fire (inclusive). Null = no upper bound.","nullable":true},"next_execution_date":{"type":"string","format":"date","description":"When the next automated run is scheduled (computed)"},"last_executed_at":{"type":"string","format":"date-time","description":"When the last automated run fired, or null if it has not yet","nullable":true}},"required":["enabled","end_date","min_monthly_savings","schedule","start_date"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"CreateCommitmentPlanTemplateArgs":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"segment_id":{"type":"string","format":"uuid","default":null,"description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","nullable":true},"name":{"type":"string","description":"Template name"},"configuration":{"description":"Plan configuration this template applies","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"auto_purchase":{"default":null,"description":"Optional auto-purchase schedule to attach","anyOf":[{"$ref":"#/components/schemas/CreateAutoPurchase"},{"type":"object","nullable":true}]}},"required":["configuration","name","provider"],"additionalProperties":false},"CreateAutoPurchase":{"type":"object","properties":{"schedule":{"type":"string","enum":["daily","weekly","monthly"],"description":"Cadence: 'daily', 'weekly', or 'monthly'"},"min_monthly_savings":{"type":"number","default":0,"description":"Dollar floor on projected monthly savings"},"enabled":{"type":"boolean","default":true,"description":"Whether the schedule is active"},"start_date":{"type":"string","format":"date","default":null,"description":"Earliest date automation may fire. Null = no lower bound.","nullable":true},"end_date":{"type":"string","format":"date","default":null,"description":"Latest date automation may fire. Null = no upper bound.","nullable":true}},"required":["schedule"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get a commitment plan template

> Returns a single template by ID.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plan Templates (Beta)","description":"Agent-friendly commitment plan template endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plan-templates/{template_id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlanTemplate"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plan Templates (Beta)"],"summary":"Get a commitment plan template","description":"Returns a single template by ID."}}},"components":{"schemas":{"CommitmentPlanTemplate":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique template identifier"},"name":{"type":"string","description":"Human-readable template name"},"segment_id":{"type":"string","format":"uuid","description":"Segment this template generates plans for"},"created_at":{"type":"string","format":"date-time","description":"When the template was created"},"is_system_generated":{"type":"boolean","description":"True if this template was created automatically by the system — the three built-ins that back Recommended / Balanced / High Savings. Describes origin, not role — system-generated templates are immutable."},"configuration":{"description":"The inputs that plans generated from this template will use","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"auto_purchase":{"description":"Scheduled auto-purchase settings, or null if the template is not on a schedule.","anyOf":[{"$ref":"#/components/schemas/AutoPurchase"},{"type":"object","nullable":true}]}},"required":["auto_purchase","configuration","created_at","id","is_system_generated","name","segment_id"],"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"AutoPurchase":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the schedule is currently active"},"schedule":{"type":"string","enum":["daily","weekly","monthly"],"description":"Cadence: 'daily', 'weekly', or 'monthly'"},"min_monthly_savings":{"type":"number","description":"Dollar floor on projected monthly savings — plans that don't clear this are skipped even when the schedule fires."},"start_date":{"type":"string","format":"date","description":"Earliest date the automation may fire (inclusive). Null = no lower bound.","nullable":true},"end_date":{"type":"string","format":"date","description":"Latest date the automation may fire (inclusive). Null = no upper bound.","nullable":true},"next_execution_date":{"type":"string","format":"date","description":"When the next automated run is scheduled (computed)"},"last_executed_at":{"type":"string","format":"date-time","description":"When the last automated run fired, or null if it has not yet","nullable":true}},"required":["enabled","end_date","min_monthly_savings","schedule","start_date"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Update a commitment plan template

> Merge-semantic update: only keys present in the body are applied. Pass \`auto\_purchase: null\` to clear an existing schedule; omit the key to leave it untouched. System-generated templates can have their \`auto\_purchase\` schedule edited but not their \`name\` or \`configuration\`.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plan Templates (Beta)","description":"Agent-friendly commitment plan template endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plan-templates/{template_id}":{"put":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentPlanTemplate"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCommitmentPlanTemplateArgs"}}}},"tags":["Commitment Plan Templates (Beta)"],"summary":"Update a commitment plan template","description":"Merge-semantic update: only keys present in the body are applied. Pass `auto_purchase: null` to clear an existing schedule; omit the key to leave it untouched. System-generated templates can have their `auto_purchase` schedule edited but not their `name` or `configuration`."}}},"components":{"schemas":{"CommitmentPlanTemplate":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique template identifier"},"name":{"type":"string","description":"Human-readable template name"},"segment_id":{"type":"string","format":"uuid","description":"Segment this template generates plans for"},"created_at":{"type":"string","format":"date-time","description":"When the template was created"},"is_system_generated":{"type":"boolean","description":"True if this template was created automatically by the system — the three built-ins that back Recommended / Balanced / High Savings. Describes origin, not role — system-generated templates are immutable."},"configuration":{"description":"The inputs that plans generated from this template will use","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"auto_purchase":{"description":"Scheduled auto-purchase settings, or null if the template is not on a schedule.","anyOf":[{"$ref":"#/components/schemas/AutoPurchase"},{"type":"object","nullable":true}]}},"required":["auto_purchase","configuration","created_at","id","is_system_generated","name","segment_id"],"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"AutoPurchase":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the schedule is currently active"},"schedule":{"type":"string","enum":["daily","weekly","monthly"],"description":"Cadence: 'daily', 'weekly', or 'monthly'"},"min_monthly_savings":{"type":"number","description":"Dollar floor on projected monthly savings — plans that don't clear this are skipped even when the schedule fires."},"start_date":{"type":"string","format":"date","description":"Earliest date the automation may fire (inclusive). Null = no lower bound.","nullable":true},"end_date":{"type":"string","format":"date","description":"Latest date the automation may fire (inclusive). Null = no upper bound.","nullable":true},"next_execution_date":{"type":"string","format":"date","description":"When the next automated run is scheduled (computed)"},"last_executed_at":{"type":"string","format":"date-time","description":"When the last automated run fired, or null if it has not yet","nullable":true}},"required":["enabled","end_date","min_monthly_savings","schedule","start_date"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"UpdateCommitmentPlanTemplateArgs":{"type":"object","properties":{"name":{"type":"string","description":"New template name"},"configuration":{"description":"Replacement configuration","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"auto_purchase":{"description":"Replacement schedule. Pass null to clear an existing schedule. Omit the key to leave the schedule untouched.","anyOf":[{"$ref":"#/components/schemas/CreateAutoPurchase"},{"type":"object","nullable":true}]}},"additionalProperties":false},"CreateAutoPurchase":{"type":"object","properties":{"schedule":{"type":"string","enum":["daily","weekly","monthly"],"description":"Cadence: 'daily', 'weekly', or 'monthly'"},"min_monthly_savings":{"type":"number","default":0,"description":"Dollar floor on projected monthly savings"},"enabled":{"type":"boolean","default":true,"description":"Whether the schedule is active"},"start_date":{"type":"string","format":"date","default":null,"description":"Earliest date automation may fire. Null = no lower bound.","nullable":true},"end_date":{"type":"string","format":"date","default":null,"description":"Latest date automation may fire. Null = no upper bound.","nullable":true}},"required":["schedule"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Delete a commitment plan template

> Delete a template. System-generated templates cannot be deleted.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Plan Templates (Beta)","description":"Agent-friendly commitment plan template endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitment-plan-templates/{template_id}":{"delete":{"responses":{"204":{"description":"No Content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Plan Templates (Beta)"],"summary":"Delete a commitment plan template","description":"Delete a template. System-generated templates cannot be deleted."}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Commitment Types (Beta)

Agent-friendly commitment type lookup

## List available commitment types

> Returns the commitment types available for the specified provider. Each type lists its supported contract terms, and each term lists the payment options that are actually offered for that (type, term) pair — the cross product of terms x payment options is NOT implied. Every leaf field (\`commitment\_type\`, \`contract\_terms\[\*].contract\_term\`, \`contract\_terms\[\*].payment\_options\[\*]\`) is the exact value you pass into a plan's \`configuration.contract\_specs\`.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitment Types (Beta)","description":"Agent-friendly commitment type lookup"}],"paths":{"/beta/v1/org/{org_id}/commitment-types":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider to list commitment types for (aws, azure, gcp).","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AvailableCommitmentType"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitment Types (Beta)"],"summary":"List available commitment types","description":"Returns the commitment types available for the specified provider. Each type lists its supported contract terms, and each term lists the payment options that are actually offered for that (type, term) pair — the cross product of terms x payment options is NOT implied. Every leaf field (`commitment_type`, `contract_terms[*].contract_term`, `contract_terms[*].payment_options[*]`) is the exact value you pass into a plan's `configuration.contract_specs`."}}},"components":{"schemas":{"AvailableCommitmentType":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier (e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2'). Pass directly as `commitment_type` in a plan's `configuration.contract_specs`."},"contract_terms":{"type":"array","description":"Contract terms this commitment type supports, each with its valid payment options. A `(contract_term, payment_option)` pair is only accepted in a plan spec if it appears here.","items":{"$ref":"#/components/schemas/AvailableContractTerm"}}},"required":["commitment_type","contract_terms"],"additionalProperties":false},"AvailableContractTerm":{"type":"object","properties":{"contract_term":{"type":"string","enum":["thirty_day_gris","one_year_gris","one_year","three_year","five_year"],"description":"Contract term identifier (e.g. 'one_year', 'three_year', 'thirty_day_gris'). Pass directly as `contract_term` in a plan's `configuration.contract_specs`."},"payment_options":{"type":"array","description":"Payment options available for this specific (commitment_type, contract_term) pair. Pass one as `payment_option` in the plan's contract spec.","items":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}}},"required":["contract_term","payment_options"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Commitments (Beta)

Agent-friendly commitment inventory endpoints

## List filterable commitment attributes

> Returns all fields that can be used in the 'filter' parameter of the commitments and commitments metrics endpoints, along with their types.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/attributes":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BaseAttribute"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"List filterable commitment attributes","tags":["Commitments (Beta)"],"description":"Returns all fields that can be used in the 'filter' parameter of the commitments and commitments metrics endpoints, along with their types."}}},"components":{"schemas":{"BaseAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean","integer","float","date","datetime","time","currency","percent","string","enum","uuid","tags"]}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get valid values for a filterable commitment attribute

> Returns the valid values for a specific filterable field. Use this to discover what values can be passed in a filter object. For example, calling with field='type' returns all commitment types like 'Compute', 'EC2Instance', etc.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/attributes/{field}":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"only_active","description":"Only return the default inventory scope (default true). By default this includes active commitments and commitments with status=recently_expired.","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"include_recently_expired","description":"When only_active=true, include commitments with status=recently_expired (default true). Set false for strictly active commitments.","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"search","description":"Text search across commitment fields","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields and date fields (`start_date`, `end_date`). Examples: {\"field\": \"type\", \"op\": \"=\", \"value\": \"Compute\"} — categorical; {\"field\": \"end_date\", \"op\": \"<\", \"value\": \"2026-06-01\"} — expiring before June 2026; {\"field\": \"monthly_net_savings\", \"op\": \">\", \"value\": 1000} — saving more than $1000/month. Date-dependent metric fields are 730-hour monthly rates matching `commitment_financials_monthly_rate.*` in the response: `monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`. `utilization` is a 0-1 fraction averaged over the window.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by. Includes the monthly-rate metrics (`monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`) and `utilization`.","schema":{"type":"string","default":"end_date","enum":["start_date","end_date","type","account_id","upfront_cost","monthly_cloud_provider_cost","monthly_recurring_cost","is_archera_guaranteed","duration_seconds","is_active","utilization","monthly_net_savings","monthly_gross_savings","monthly_premiums","monthly_estimated_rebate"]},"required":false},{"in":"query","name":"desc","description":"Sort descending. Default false — combined with the default order_by=end_date this surfaces the earliest-expiring commitments first, which is the common drilldown.","schema":{"type":"boolean","default":false},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attribute"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Get valid values for a filterable commitment attribute","tags":["Commitments (Beta)"],"description":"Returns the valid values for a specific filterable field. Use this to discover what values can be passed in a filter object. For example, calling with field='type' returns all commitment types like 'Compute', 'EC2Instance', etc."}}},"components":{"schemas":{"Attribute":{"oneOf":[{"$ref":"#/components/schemas/BooleanAttribute"},{"$ref":"#/components/schemas/UUIDAttribute"},{"$ref":"#/components/schemas/StringAttribute"},{"$ref":"#/components/schemas/IntegerAttribute"},{"$ref":"#/components/schemas/FloatAttribute"},{"$ref":"#/components/schemas/CurrencyAttribute"},{"$ref":"#/components/schemas/PercentAttribute"},{"$ref":"#/components/schemas/DateTimeAttribute"},{"$ref":"#/components/schemas/DateAttribute"},{"$ref":"#/components/schemas/TimeAttribute"},{"$ref":"#/components/schemas/EnumAttribute"},{"$ref":"#/components/schemas/TagsAttribute"}],"discriminator":{"propertyName":"type","mapping":{"boolean":"#/components/schemas/BooleanAttribute","uuid":"#/components/schemas/UUIDAttribute","string":"#/components/schemas/StringAttribute","integer":"#/components/schemas/IntegerAttribute","float":"#/components/schemas/FloatAttribute","currency":"#/components/schemas/CurrencyAttribute","percent":"#/components/schemas/PercentAttribute","datetime":"#/components/schemas/DateTimeAttribute","date":"#/components/schemas/DateAttribute","time":"#/components/schemas/TimeAttribute","enum":"#/components/schemas/EnumAttribute","tags":"#/components/schemas/TagsAttribute"}}},"BooleanAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false},"UUIDAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["uuid"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"StringAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["string"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"IntegerAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["integer"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"FloatAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["float"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"CurrencyAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["currency"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"PercentAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["percent"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateTimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["datetime"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["date"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"TimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["time"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"EnumAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["enum"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"TagsAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["tags"],"readOnly":true},"tags":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get commitment inventory

> Returns the organization's commitment inventory for the specified provider. By default returns active commitments plus commitments with status=recently\_expired. Set include\_recently\_expired=false for strictly active commitments, or only\_active=false to include expired and other non-active commitments.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"only_active","description":"Only return the default inventory scope (default true). By default this includes active commitments and commitments with status=recently_expired.","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"include_recently_expired","description":"When only_active=true, include commitments with status=recently_expired (default true). Set false for strictly active commitments.","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"search","description":"Text search across commitment fields","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields and date fields (`start_date`, `end_date`). Examples: {\"field\": \"type\", \"op\": \"=\", \"value\": \"Compute\"} — categorical; {\"field\": \"end_date\", \"op\": \"<\", \"value\": \"2026-06-01\"} — expiring before June 2026; {\"field\": \"monthly_net_savings\", \"op\": \">\", \"value\": 1000} — saving more than $1000/month. Date-dependent metric fields are 730-hour monthly rates matching `commitment_financials_monthly_rate.*` in the response: `monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`. `utilization` is a 0-1 fraction averaged over the window.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by. Includes the monthly-rate metrics (`monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`) and `utilization`.","schema":{"type":"string","default":"end_date","enum":["start_date","end_date","type","account_id","upfront_cost","monthly_cloud_provider_cost","monthly_recurring_cost","is_archera_guaranteed","duration_seconds","is_active","utilization","monthly_net_savings","monthly_gross_savings","monthly_premiums","monthly_estimated_rebate"]},"required":false},{"in":"query","name":"desc","description":"Sort descending. Default false — combined with the default order_by=end_date this surfaces the earliest-expiring commitments first, which is the common drilldown.","schema":{"type":"boolean","default":false},"required":false},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":20,"minimum":1,"maximum":10000},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommitmentWithMetrics"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments (Beta)"],"summary":"Get commitment inventory","description":"Returns the organization's commitment inventory for the specified provider. By default returns active commitments plus commitments with status=recently_expired. Set include_recently_expired=false for strictly active commitments, or only_active=false to include expired and other non-active commitments."}}},"components":{"schemas":{"CommitmentWithMetrics":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"utilization":{"type":"number","description":"Utilization rate (0-1) over the metrics period","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars paid at signing for this commitment. NOT a rate — do not sum with monthly-rate fields. 0 for commitments with no-upfront payment options."},"commitment_financials_monthly_rate":{"description":"Commitment economics as 730-hour monthly rates — cost, savings, and on-demand baseline. NOT a calendar month (672-744 hours). commitment_savings.rebate is populated with an actual value (possibly 0).","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get commitment portfolio summary

> Returns an aggregated summary of the organization's current commitment inventory including total savings, costs, utilization, and breakdowns by term length and commitment type. By default includes commitments with status=recently\_expired; set include\_recently\_expired=false for strictly active commitments. All metrics are based on the most recent day of usage data.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/summary":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"include_recently_expired","description":"Include commitments with status=recently_expired in the current inventory summary (default true). Set false for a strictly active summary.","schema":{"type":"boolean","default":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentSummary"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments (Beta)"],"summary":"Get commitment portfolio summary","description":"Returns an aggregated summary of the organization's current commitment inventory including total savings, costs, utilization, and breakdowns by term length and commitment type. By default includes commitments with status=recently_expired; set include_recently_expired=false for strictly active commitments. All metrics are based on the most recent day of usage data."}}},"components":{"schemas":{"CommitmentSummary":{"type":"object","properties":{"total_commitments":{"type":"integer","description":"Total number of commitments in the summary scope. By default this includes active commitments and status=recently_expired commitments."},"total_active_commitments":{"type":"integer","description":"Number of commitments in the summary scope with is_active=true."},"recently_expired_commitments":{"type":"integer","description":"Number of commitments with status=recently_expired included in this summary scope. Zero when include_recently_expired=false."},"total_guaranteed_commitments":{"type":"integer","description":"Number of Archera Guaranteed Commitments in the summary scope"},"total_native_commitments":{"type":"integer","description":"Number of native cloud commitments (not guaranteed) in the summary scope"},"average_utilization":{"type":"number","description":"Cost-weighted average utilization across the summary scope (0-1)"},"expiring_30_days":{"type":"integer","description":"Number of commitments expiring in the next 30 days"},"expiring_90_days":{"type":"integer","description":"Number of commitments expiring in the next 90 days"},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials aggregated across the summary scope. commitment_savings.rebate is the sum of rebates across commitments.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"by_term":{"type":"array","description":"Breakdown by term length. Guaranteed commitments are grouped by their guarantee period (e.g. '30-Day Guaranteed', '1-Year Guaranteed'), native commitments by their cloud term (e.g. '1-Year Native', '3-Year Native').","items":{"$ref":"#/components/schemas/BreakdownEntry"}},"by_type":{"type":"array","description":"Breakdown by commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')","items":{"$ref":"#/components/schemas/BreakdownEntry"}}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"BreakdownEntry":{"type":"object","properties":{"label":{"type":"string","description":"Group label"},"count":{"type":"integer","description":"Number of commitments in this group"},"average_utilization":{"type":"number","description":"Cost-weighted average utilization within this group (0-1)"},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this group. commitment_savings.rebate is the sum of rebates for commitments in this group.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get commitment details

> Returns detailed information about a specific commitment including daily utilization data and an attribution summary showing which resources are covered. Optionally specify start\_date/end\_date for the utilization and attribution data; defaults to the most recent day.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/{commitment_id}":{"get":{"parameters":[{"in":"query","name":"start_date","description":"Start date for utilization/attribution data (YYYY-MM-DD). Defaults to 1 day ago.","schema":{"type":"string","format":"date","default":null,"nullable":true},"required":false},{"in":"query","name":"end_date","description":"End date for utilization/attribution data (YYYY-MM-DD). Defaults to today.","schema":{"type":"string","format":"date","default":null,"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments (Beta)"],"summary":"Get commitment details","description":"Returns detailed information about a specific commitment including daily utilization data and an attribution summary showing which resources are covered. Optionally specify start_date/end_date for the utilization and attribution data; defaults to the most recent day."}}},"components":{"schemas":{"CommitmentDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"utilization":{"type":"number","description":"Utilization rate (0-1) over the metrics period","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars paid at signing for this commitment. NOT a rate — do not sum with monthly-rate fields. 0 for commitments with no-upfront payment options."},"commitment_financials_monthly_rate":{"description":"Commitment economics as 730-hour monthly rates — cost, savings, and on-demand baseline. NOT a calendar month (672-744 hours). commitment_savings.rebate is populated with an actual value (possibly 0).","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"daily_utilizations":{"type":"array","description":"Daily utilization data points for the effective time period","items":{"$ref":"#/components/schemas/DailyUtilization"}},"attribution_summary":{"type":"array","description":"Resources covered by this commitment, aggregated by service, account, region, and resource type","items":{"$ref":"#/components/schemas/AttributionSummaryEntry"}},"covered_resources":{"type":"array","description":"Per-resource breakdown of usage covered by this commitment over the period.","items":{"$ref":"#/components/schemas/CoveredResourceEntry"}}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"DailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of this data point"},"active_hours":{"type":"number","description":"Hours the commitment was active on this day (0-24)","nullable":true},"utilization":{"type":"number","description":"Utilization rate for this day (0-1)"},"commitment_financials_daily_total":{"description":"Sum of commitment economics for this single day (NOT a monthly rate). commitment_savings.rebate is the rebate accrued on this day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"AttributionSummaryEntry":{"type":"object","properties":{"service":{"type":"string","description":"Cloud service name","nullable":true},"account_id":{"type":"string","description":"Cloud account ID","nullable":true},"region":{"type":"string","description":"Cloud region","nullable":true},"resource_type":{"type":"string","description":"Resource type — instance family for compute, usage type for other services, or SKU name as fallback","nullable":true},"resource_count":{"type":"integer","description":"Number of resources in this group"},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this group. cloud_provider_cost has `{total}` only — per-group data doesn't split into recurring / amortized_upfront. archera_premium is allocated proportionally by cloud_provider_cost share of the parent commitment; summing across groups yields the parent commitment's monthly premium. commitment_savings has no rebate field at this level — rebate is a commitment-wide concept.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"attributed_utilization":{"type":"number","description":"Share of the commitment's overall utilization attributed to this group (0-1). All groups' attributed_utilization values sum to the commitment's total utilization."}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CoveredResourceEntry":{"type":"object","properties":{"resource_id":{"type":"string","description":"Archera resource id covered by this commitment."},"name":{"type":"string","description":"Display name of the resource. May be null.","nullable":true},"covered_usage":{"type":"number","description":"Sum of usage_amount_normalized this commitment covered on this resource over the period."},"total_usage":{"type":"number","description":"Sum of usage_amount_normalized across usage/commitment and usage/ondemand line items on this resource, restricted to the (resource, catalog SKU) pairs this commitment covered so the units match `covered_usage`."},"coverage_pct":{"type":"number","description":"Spend-based coverage: the on-demand-equivalent cost covered by this commitment divided by total on-demand-equivalent cost across the covered SKU pairs, in [0, 1]. 0 when total on-demand-equivalent cost is 0."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Compare offer alternatives across commitments in a portfolio

> Returns per-commitment offer alternatives plus portfolio-wide rollups for each (contract\_term, payment\_option) hypothetical. Designed to answer 'how much have I left on the table' / 'what if my portfolio were all 3-year' in a single call: hypothetical\_totals carries the rolled-up financials and delta\_vs\_current, with per-commitment resolution exposed for transparency. Each commitment lands at the target term when available, else the longest available term <= target with the same payment option (GRI preferred within tier), else its current term. Read-only and informational: there is no follow-up write action — active commitments cannot be swapped programmatically. To actually change term length or offer, the user should reach out to support.\
> \
> \*\*Single-commitment drilldown\*\*: pass \`commitment\_ids=\[single\_id]\` to scope the response to one commitment. Same shape, just one entry in \`data\` and per-(term,payment) rollups that span only that commitment.\
> \
> \*\*Sizing & underutilization caveat\*\*: candidate grids per commitment are sized from each commitment's SKU usage in the most recent fully-recorded day, NOT from nominal capacity. Per-commitment \`utilization\_warning\` and the rollup-level \`low\_utilization\_commitment\_count\` flag commitments below 50% utilization — for those rows, candidate financials are projected against hours that aren't actually consumed and the comparison is structurally less informative. Surface the count when non-zero so totals are framed honestly.\
> \
> \*\*Rebate handling\*\*: \`current.commitment\_financials\_monthly\_rate.commitment\_savings.net\` is \`gross - premium\` (no rebate), apples-to-apples with candidates which have no rebate concept. For an active commitment earning rebate income this differs from \`commitment\_details\`'s net (which includes rebate). For true current economics including rebate, use \`commitment\_details\`.\
> \
> \*\*Skipped commitments\*\*: commitments that fail to build a grid (typically 'no recent SKU usage') are listed in \`skipped\_commitments\` with a reason, NOT silently dropped. They contribute to neither current\_totals nor hypothetical\_totals.\
> \
> \*\*Presentation note\*\*: \`partial\_upfront\` and \`all\_upfront\` candidate offers should be de-emphasized by default — only surface them when an in-scope commitment already has an upfront component or the caller has signaled interest in upfront trades. Use the \`payment\_options\` query arg to filter.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/comparison":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"commitment_ids","description":"Optional subset of commitments to compare. If omitted, defaults to all currently-active commitments for the provider.","schema":{"type":"array","default":null,"items":{"type":"string","format":"uuid"},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"contract_terms","description":"Optional list of target terms to roll up. If omitted, the response includes a hypothetical for every distinct contract_term that appears in any commitment's candidates after the payment-option filter.","schema":{"type":"array","default":null,"items":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"payment_options","description":"Payment options to include. Defaults to no_upfront only — most users are uncomfortable with cash at signing, so this matches the default framing for portfolio comparisons. Pass partial_upfront / all_upfront explicitly to surface those.","schema":{"type":"array","items":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":false,"explode":true,"style":"form"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitmentOfferComparisonResponse"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments (Beta)"],"summary":"Compare offer alternatives across commitments in a portfolio","description":"Returns per-commitment offer alternatives plus portfolio-wide rollups for each (contract_term, payment_option) hypothetical. Designed to answer 'how much have I left on the table' / 'what if my portfolio were all 3-year' in a single call: hypothetical_totals carries the rolled-up financials and delta_vs_current, with per-commitment resolution exposed for transparency. Each commitment lands at the target term when available, else the longest available term <= target with the same payment option (GRI preferred within tier), else its current term. Read-only and informational: there is no follow-up write action — active commitments cannot be swapped programmatically. To actually change term length or offer, the user should reach out to support.\n\n**Single-commitment drilldown**: pass `commitment_ids=[single_id]` to scope the response to one commitment. Same shape, just one entry in `data` and per-(term,payment) rollups that span only that commitment.\n\n**Sizing & underutilization caveat**: candidate grids per commitment are sized from each commitment's SKU usage in the most recent fully-recorded day, NOT from nominal capacity. Per-commitment `utilization_warning` and the rollup-level `low_utilization_commitment_count` flag commitments below 50% utilization — for those rows, candidate financials are projected against hours that aren't actually consumed and the comparison is structurally less informative. Surface the count when non-zero so totals are framed honestly.\n\n**Rebate handling**: `current.commitment_financials_monthly_rate.commitment_savings.net` is `gross - premium` (no rebate), apples-to-apples with candidates which have no rebate concept. For an active commitment earning rebate income this differs from `commitment_details`'s net (which includes rebate). For true current economics including rebate, use `commitment_details`.\n\n**Skipped commitments**: commitments that fail to build a grid (typically 'no recent SKU usage') are listed in `skipped_commitments` with a reason, NOT silently dropped. They contribute to neither current_totals nor hypothetical_totals.\n\n**Presentation note**: `partial_upfront` and `all_upfront` candidate offers should be de-emphasized by default — only surface them when an in-scope commitment already has an upfront component or the caller has signaled interest in upfront trades. Use the `payment_options` query arg to filter."}}},"components":{"schemas":{"CommitmentOfferComparisonResponse":{"type":"object","properties":{"current_totals":{"description":"Portfolio-wide totals for the commitments currently in scope today. Use as the baseline when interpreting hypothetical deltas.","allOf":[{"$ref":"#/components/schemas/CommitmentOfferComparisonTotals"}]},"hypothetical_totals":{"type":"array","description":"One entry per (contract_term, payment_option) combination. Each entry's totals + delta_vs_current answer 'what's the portfolio-wide impact of this term?' in one place — no client-side summing across commitments required.","items":{"$ref":"#/components/schemas/HypotheticalCommitmentTotal"}},"data":{"type":"array","description":"Per-commitment detail. Use when the user wants to drill into a specific commitment's alternatives.","items":{"$ref":"#/components/schemas/CommitmentOfferComparisonRow"}},"skipped_commitments":{"type":"array","description":"Commitments that couldn't be compared (e.g. no recent SKU usage). Surface to the user so the rollup scope is honest — these commitments contribute neither to current_totals nor to hypothetical_totals.","items":{"$ref":"#/components/schemas/SkippedCommitment"}}},"required":["current_totals","data","hypothetical_totals","skipped_commitments"],"additionalProperties":false},"CommitmentOfferComparisonTotals":{"type":"object","properties":{"commitment_financials_monthly_rate":{"description":"730-hour monthly rate financials summed across the commitments in scope. Same shape as on plans / line items. No-rebate basis to keep totals apples-to-apples with hypothetical_totals.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars at signing across the commitments in scope. NOT a rate — do not sum with monthly-rate fields."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"HypotheticalCommitmentTotal":{"type":"object","properties":{"contract_term":{"description":"Target contract term for this hypothetical.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Target payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"description":"Rolled-up monthly-rate financials assuming each commitment adopts its candidate per the fallback rule.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars across the commitments under this hypothetical. NOT a rate."},"delta_vs_current":{"description":"Axis-by-axis difference vs current_totals. The headline 'how much did I leave on the table' answer is delta_vs_current.monthly_net_savings.","allOf":[{"$ref":"#/components/schemas/HypotheticalCommitmentDelta"}]},"commitments":{"type":"array","description":"Per-commitment resolution for this hypothetical. Use to call out fallbacks ('14 of 20 commitments would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current') and underutilized-commitment caveats.","items":{"$ref":"#/components/schemas/HypotheticalCommitmentEntry"}},"low_utilization_commitment_count":{"type":"integer","description":"Number of commitments in this rollup whose recent utilization is below 50%. Convenience aggregate of the per-row utilization_warning flags. Surface when non-zero: the rollup deltas may overstate the savings opportunity since underutilized commitments project candidate savings against hours that aren't actually consumed."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","commitments","contract_term","delta_vs_current","low_utilization_commitment_count","payment_option"],"additionalProperties":false},"HypotheticalCommitmentDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the portfolio does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"HypotheticalCommitmentEntry":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"actual_term":{"description":"The contract term this commitment actually contributes to the rollup at. Equals the target when an exact match exists; otherwise the longest available term <= target with the same payment option, or the commitment's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this commitment contributes. Equals the target except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this commitment landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."},"utilization_warning":{"type":"boolean","description":"True if this commitment's recent utilization is below 50% — the comparison for it is less informative because candidates are sized from observed usage, not the commitment's nominal capacity. Surface to the user when present so the rollup is framed honestly."}},"required":["actual_payment_option","actual_term","actual_term_reason","commitment_id","utilization_warning"],"additionalProperties":false},"CommitmentOfferComparisonRow":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"current":{"description":"The existing commitment as the baseline — full identity, utilization, and current economics. Same shape as the singular tool's `current` block.","allOf":[{"$ref":"#/components/schemas/CurrentCommitmentEntry"}]},"candidates":{"type":"array","description":"Candidate offer alternatives sized for the same observed usage, filtered to the requested contract_terms and payment_options. Each candidate's delta_vs_current is per-COMMITMENT (NOT portfolio-wide). Sorted by net monthly savings, best first. May be empty when no valid replacements exist.","items":{"$ref":"#/components/schemas/CandidateOfferEntry_Exclude_IsCurrent"}}},"required":["candidates","commitment_id","current"],"additionalProperties":false},"CurrentCommitmentEntry":{"type":"object","properties":{"commitment":{"description":"Full identity of the existing commitment — id, provider, type, instance/region/account, dates, payment_option, contract_term, guarantee info. Same shape as `commitment_details`'s identity fields (no metrics).","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"utilization":{"type":"number","description":"Cost-weighted utilization rate (0-1) over the recent observation period the comparison is built against. The grid sizes candidates from observed usage, so utilization context matters for framing — low utilization means candidates reflect alternatives sized for actual usage, not for the commitment's original capacity.","nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1), NET basis (`(gross - premium) / on-demand`) — apples-to-apples with candidates."},"breakeven_days":{"type":"number","description":"Days until the existing commitment paid for itself, computed from upfront_cost and hourly net savings. Null if net savings are not positive.","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars paid at signing for this commitment. NOT a rate — do not sum with monthly-rate fields. 0 for no-upfront payment options."},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for the existing commitment in the no-rebate shape used by candidates. `commitment_savings.net` here is `gross - premium`, NOT including any rebate the commitment may be accruing — kept on the no-rebate basis so deltas vs candidates are apples-to-apples. For true current economics including rebate income, call `commitment_details`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"CandidateOfferEntry_Exclude_IsCurrent":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost).","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","allOf":[{"$ref":"#/components/schemas/OfferComparisonDelta"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":"number","description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven.","nullable":true}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false},"SkippedCommitment":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"reason":{"type":"string","description":"Why this commitment was skipped — typically 'no recent SKU usage' (commitment has no usage attributed to it in the recent observation window, so the candidate grid can't be built). Surface to the user rather than dropping silently."}},"required":["commitment_id","reason"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get commitment portfolio metrics over time

> Returns daily commitment metrics (savings, costs, utilization, premiums, rebates) over a time period. Includes per-day data points and period totals. Note: coverage is not included here — coverage is a segment-level metric. Use the /metrics/daily-coverage endpoint for coverage trends.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Commitments (Beta)","description":"Agent-friendly commitment inventory endpoints"}],"paths":{"/beta/v1/org/{org_id}/commitments/metrics":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"start_date","description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date (YYYY-MM-DD, exclusive)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"search","description":"Text search across commitment fields","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — same shape as `/commitments`. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields and date fields (`start_date`, `end_date`). Date-dependent metric fields are 730-hour monthly rates evaluated over the requested `start_date` / `end_date` window: `monthly_net_savings`, `monthly_gross_savings`, `monthly_premiums`, `monthly_estimated_rebate`. `utilization` is a 0-1 fraction averaged over the window. Note that the RESPONSE on this endpoint reports period totals (`commitment_financials_period_total.*`), not monthly rates — so a filter like `{\"field\": \"monthly_net_savings\", \"op\": \">\", \"value\": 1000}` selects commitments saving at >$1000/month rate during the window, even though the response will show the dollar total accumulated over the window itself.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Commitments (Beta)"],"summary":"Get commitment portfolio metrics over time","description":"Returns daily commitment metrics (savings, costs, utilization, premiums, rebates) over a time period. Includes per-day data points and period totals. Note: coverage is not included here — coverage is a segment-level metric. Use the /metrics/daily-coverage endpoint for coverage trends."}}},"components":{"schemas":{"MetricsResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"utilization":{"type":"number","description":"Cost-weighted average utilization across the period (0-1)"},"underutilized_commitment_cost":{"type":"number","description":"Total cost of unused commitment capacity for the period"},"commitment_financials_period_total":{"description":"Sum of commitment economics aggregated across commitments over the requested date range. commitment_savings.rebate is the sum of per-commitment rebates for the period.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"data":{"type":"array","description":"Per-day data points for trend analysis","items":{"$ref":"#/components/schemas/DailyMetricsDataPoint"}}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"DailyMetricsDataPoint":{"type":"object","properties":{"date":{"type":"string","description":"Date (YYYY-MM-DD)"},"utilization":{"type":"number","description":"Cost-weighted utilization rate for this day (0-1)"},"underutilized_commitment_cost":{"type":"number","description":"Cost of unused/underutilized commitment capacity for this day"},"commitment_financials_daily_total":{"description":"Sum of commitment economics aggregated across commitments for this day. commitment_savings.rebate is the sum of per-commitment rebates for this day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Metrics (Beta)

Organization-level metrics and overview

## Get organization overview

> Returns a high-level overview of the organization's commitment performance including savings, coverage, utilization, missed savings opportunities, automation status, and prioritized recommended actions.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Metrics (Beta)","description":"Organization-level metrics and overview"}],"paths":{"/beta/v1/org/{org_id}/metrics/overview":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Overview"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Metrics (Beta)"],"summary":"Get organization overview","description":"Returns a high-level overview of the organization's commitment performance including savings, coverage, utilization, missed savings opportunities, automation status, and prioritized recommended actions."}}},"components":{"schemas":{"Overview":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Current monthly net savings rate from active commitments"},"expiring_monthly_savings":{"type":"number","description":"Monthly savings at risk from commitments expiring in the next 30 days"},"coverage":{"type":"number","description":"Overall spend-based commitment coverage ratio (0-1): share of reservable on-demand-equivalent spend covered, not the share of hours or usage units.","nullable":true},"utilization":{"type":"number","description":"Overall commitment utilization ratio (0-1)","nullable":true},"purchase_missed_savings":{"type":"number","description":"Monthly savings available by applying the recommended commitment plan. 0 if a plan has already been applied."},"buyback_missed_savings":{"type":"number","description":"Monthly savings available from pending buyback opportunities"},"purchase_automation_enabled":{"type":"boolean","description":"Whether automatic commitment purchasing is enabled"},"buyback_automation_enabled":{"type":"boolean","description":"Whether automatic buyback/sellback is enabled"},"has_actioned_plan":{"type":"boolean","description":"Whether the organization has ever applied a commitment plan"},"data_available_since":{"type":"string","format":"date","description":"Earliest date cost data is available for this provider (null if no data)","nullable":true},"recommended_actions":{"type":"array","description":"Prioritized list of recommended actions to improve savings","items":{"$ref":"#/components/schemas/RecommendedAction"}}},"additionalProperties":false},"RecommendedAction":{"type":"object","properties":{"action":{"type":"string","description":"Action identifier (e.g. 'apply_recommended_plan')"},"description":{"type":"string","description":"Human-readable description of the recommended action"},"monthly_impact":{"type":"number","description":"Estimated monthly savings impact if action is taken","nullable":true},"priority":{"type":"string","description":"Priority level: 'high', 'medium', or 'low'"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get daily coverage

> Returns spend-based commitment coverage over the requested date range, weighted by each day's reservable on-demand-equivalent spend, plus per-day values for trend analysis. Coverage is not weighted by hours or usage units.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Metrics (Beta)","description":"Organization-level metrics and overview"}],"paths":{"/beta/v1/org/{org_id}/metrics/daily-coverage":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"segment_id","description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false},{"in":"query","name":"start_date","description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date (YYYY-MM-DD, exclusive)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"group_by","description":"Dimension to group daily metrics by: 'service', 'account', or 'region'. If omitted, `groups` is null and the top-level response is the overall total.","schema":{"default":null,"type":"string","enum":["service","account","region",null],"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyCoverageResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Metrics (Beta)"],"summary":"Get daily coverage","description":"Returns spend-based commitment coverage over the requested date range, weighted by each day's reservable on-demand-equivalent spend, plus per-day values for trend analysis. Coverage is not weighted by hours or usage units."}}},"components":{"schemas":{"DailyCoverageResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"coverage":{"type":"number","description":"Spend-based commitment coverage across the effective date range (0-1): the share of reservable on-demand-equivalent spend covered by commitments, weighted by each day's spend rather than hours or usage units.","nullable":true},"daily":{"type":"array","description":"Per-day data points for trend analysis.","items":{"$ref":"#/components/schemas/DailyCoveragePoint"}},"groups":{"type":"array","description":"Grouped coverage series. Null when group_by is omitted; otherwise one entry per service, account, or region. Empty when group_by is set but no groups match.","items":{"$ref":"#/components/schemas/DailyCoverageGroup"},"nullable":true}},"additionalProperties":false},"DailyCoveragePoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"coverage":{"type":"number","description":"Spend-based commitment coverage for this day (0-1)."}},"additionalProperties":false},"DailyCoverageGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (service name, account ID, or region)."},"coverage":{"type":"number","description":"Spend-based commitment coverage for this group across the range (0-1), weighted by each day's reservable on-demand-equivalent spend.","nullable":true},"daily":{"type":"array","description":"Per-day coverage values for this group.","items":{"$ref":"#/components/schemas/DailyCoveragePoint"}}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get daily savings

> Returns daily commitment savings with cost and savings grouped, plus period-level totals.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Metrics (Beta)","description":"Organization-level metrics and overview"}],"paths":{"/beta/v1/org/{org_id}/metrics/daily-savings":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"segment_id","description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false},{"in":"query","name":"start_date","description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date (YYYY-MM-DD, exclusive)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"group_by","description":"Dimension to group daily metrics by: 'service', 'account', or 'region'. If omitted, `groups` is null and the top-level response is the overall total.","schema":{"default":null,"type":"string","enum":["service","account","region",null],"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailySavingsResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Metrics (Beta)"],"summary":"Get daily savings","description":"Returns daily commitment savings with cost and savings grouped, plus period-level totals."}}},"components":{"schemas":{"DailySavingsResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"commitment_financials_period_total":{"description":"Sum of commitment economics across the effective date range.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"daily":{"type":"array","description":"Per-day data points for trend analysis.","items":{"$ref":"#/components/schemas/DailySavingsPoint"}},"groups":{"type":"array","description":"Grouped savings series. Null when group_by is omitted; otherwise one entry per service, account, or region. Empty when group_by is set but no groups match.","items":{"$ref":"#/components/schemas/DailySavingsGroup"},"nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"DailySavingsPoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"commitment_financials_daily_total":{"description":"Sum of commitment economics for this single day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"additionalProperties":false},"DailySavingsGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (service name, account ID, or region)."},"commitment_financials_period_total":{"description":"Sum of commitment economics for this group over the range.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"daily":{"type":"array","description":"Per-day savings values for this group.","items":{"$ref":"#/components/schemas/DailySavingsPoint"}}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get daily reservable cost breakdown

> Returns daily cost for reservable services over the date range, split by pricing type (uncovered, commitment-covered). The commitment bucket is further split into cloud\_provider\_cost + archera\_premium. Includes period-level totals and total savings vs on-demand baseline.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Metrics (Beta)","description":"Organization-level metrics and overview"}],"paths":{"/beta/v1/org/{org_id}/metrics/daily-reservable-cost":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"segment_id","description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false},{"in":"query","name":"start_date","description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date (YYYY-MM-DD, exclusive)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"group_by","description":"Dimension to group daily metrics by: 'service', 'account', or 'region'. If omitted, `groups` is null and the top-level response is the overall total.","schema":{"default":null,"type":"string","enum":["service","account","region",null],"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyReservableCostResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Metrics (Beta)"],"summary":"Get daily reservable cost breakdown","description":"Returns daily cost for reservable services over the date range, split by pricing type (uncovered, commitment-covered). The commitment bucket is further split into cloud_provider_cost + archera_premium. Includes period-level totals and total savings vs on-demand baseline."}}},"components":{"schemas":{"DailyReservableCostResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"total_cost":{"type":"number","description":"Total paid for reservable services over the effective date range."},"if_all_ondemand_cost":{"type":"number","description":"On-demand baseline: what the range would cost at on-demand prices."},"total_savings":{"type":"number","description":"Total savings across all discount types (if_all_ondemand_cost - total_cost)."},"by_pricing_type":{"$ref":"#/components/schemas/PricingTypeBreakdown"},"daily":{"type":"array","description":"Per-day data points for trend analysis.","items":{"$ref":"#/components/schemas/DailyReservableCostPoint"}},"groups":{"type":"array","description":"Grouped reservable-cost series. Null when group_by is omitted; otherwise one entry per service, account, or region. Empty when group_by is set but no groups match.","items":{"$ref":"#/components/schemas/DailyReservableCostGroup"},"nullable":true}},"additionalProperties":false},"PricingTypeBreakdown":{"type":"object","properties":{"ondemand_cost":{"type":"number","description":"Cost from uncovered usage."},"commitment_cost":{"description":"Total cost from commitment-covered usage, with breakdown into cloud provider portion and Archera premium.","allOf":[{"$ref":"#/components/schemas/CommitmentCost"}]}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"DailyReservableCostPoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"total_cost":{"type":"number","description":"Total paid for reservable services this day across uncovered and commitment-covered pricing (ondemand_cost + commitment_cost.total). Headline 'cost'."},"if_all_ondemand_cost":{"type":"number","description":"What total_cost would be if all reservable usage ran at on-demand prices. Baseline for total savings across all discount types."},"by_pricing_type":{"$ref":"#/components/schemas/PricingTypeBreakdown"}},"additionalProperties":false},"DailyReservableCostGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (service name, account ID, or region)."},"total_cost":{"type":"number","description":"Total paid for reservable services in this group."},"if_all_ondemand_cost":{"type":"number","description":"On-demand baseline for this group's reservable services."},"total_savings":{"type":"number","description":"Total savings for this group across all discount types (if_all_ondemand_cost - total_cost)."},"by_pricing_type":{"$ref":"#/components/schemas/PricingTypeBreakdown"},"daily":{"type":"array","description":"Per-day cost values for this group.","items":{"$ref":"#/components/schemas/DailyReservableCostPoint"}}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Moneyback Guarantees (Beta)

Monthly savings rates delivered through Moneyback Guarantee rebates and releases

## Get monthly Moneyback Guarantee savings

> Returns 730-hour monthly savings rates delivered through commitment rebates and releases. Rebate totals are normalized over the requested period; release savings are the monthly commitment cost eliminated by commitments released during the period. The end date is exclusive.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Moneyback Guarantees (Beta)","description":"Monthly savings rates delivered through Moneyback Guarantee rebates and releases"}],"paths":{"/beta/v1/org/{org_id}/moneyback-guarantees/savings":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"start_date","description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date (YYYY-MM-DD, exclusive)","schema":{"type":"string","format":"date"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoneybackGuaranteeMonthlySavings"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Moneyback Guarantees (Beta)"],"summary":"Get monthly Moneyback Guarantee savings","description":"Returns 730-hour monthly savings rates delivered through commitment rebates and releases. Rebate totals are normalized over the requested period; release savings are the monthly commitment cost eliminated by commitments released during the period. The end date is exclusive."}}},"components":{"schemas":{"MoneybackGuaranteeMonthlySavings":{"type":"object","properties":{"monthly_rebate_savings":{"type":"number","description":"Rebates delivered over the requested period, normalized to a 730-hour monthly rate"},"monthly_release_savings":{"type":"number","description":"730-hour monthly commitment cost eliminated by commitments resold during the requested period"},"monthly_total_savings":{"type":"number","description":"Sum of monthly_rebate_savings and monthly_release_savings"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Segments (Beta)

Segment management endpoints

## List filterable segment fields

> Returns the fields that can be used in segment filter expressions. Call /segments/filters/\<field> for valid values within the provider scope.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments/filters":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BaseAttribute"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Segments (Beta)"],"summary":"List filterable segment fields","description":"Returns the fields that can be used in segment filter expressions. Call /segments/filters/<field> for valid values within the provider scope."}}},"components":{"schemas":{"BaseAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean","integer","float","date","datetime","time","currency","percent","string","enum","uuid","tags"]}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get valid values for a segment filter field

> Returns the distinct values for a given segment filter field, scoped to the provider, org, current attribution, and active integrations.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments/filters/{field}":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attribute"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Segments (Beta)"],"summary":"Get valid values for a segment filter field","description":"Returns the distinct values for a given segment filter field, scoped to the provider, org, current attribution, and active integrations."}}},"components":{"schemas":{"Attribute":{"oneOf":[{"$ref":"#/components/schemas/BooleanAttribute"},{"$ref":"#/components/schemas/UUIDAttribute"},{"$ref":"#/components/schemas/StringAttribute"},{"$ref":"#/components/schemas/IntegerAttribute"},{"$ref":"#/components/schemas/FloatAttribute"},{"$ref":"#/components/schemas/CurrencyAttribute"},{"$ref":"#/components/schemas/PercentAttribute"},{"$ref":"#/components/schemas/DateTimeAttribute"},{"$ref":"#/components/schemas/DateAttribute"},{"$ref":"#/components/schemas/TimeAttribute"},{"$ref":"#/components/schemas/EnumAttribute"},{"$ref":"#/components/schemas/TagsAttribute"}],"discriminator":{"propertyName":"type","mapping":{"boolean":"#/components/schemas/BooleanAttribute","uuid":"#/components/schemas/UUIDAttribute","string":"#/components/schemas/StringAttribute","integer":"#/components/schemas/IntegerAttribute","float":"#/components/schemas/FloatAttribute","currency":"#/components/schemas/CurrencyAttribute","percent":"#/components/schemas/PercentAttribute","datetime":"#/components/schemas/DateTimeAttribute","date":"#/components/schemas/DateAttribute","time":"#/components/schemas/TimeAttribute","enum":"#/components/schemas/EnumAttribute","tags":"#/components/schemas/TagsAttribute"}}},"BooleanAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false},"UUIDAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["uuid"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"StringAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["string"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"IntegerAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["integer"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"FloatAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["float"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"CurrencyAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["currency"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"PercentAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["percent"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateTimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["datetime"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["date"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"TimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["time"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"EnumAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["enum"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"TagsAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["tags"],"readOnly":true},"tags":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## List segments

> Returns all segments for the specified provider with pre-aggregated monthly metrics.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Segments (Beta)"],"summary":"List segments","description":"Returns all segments for the specified provider with pre-aggregated monthly metrics."}}},"components":{"schemas":{"Segment":{"type":"object","properties":{"id":{"type":"string","description":"Unique segment identifier"},"name":{"type":"string","description":"Segment name"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"is_system_generated":{"type":"boolean","description":"True if this segment was created automatically by the system (e.g. the provider-resources default segment). Describes origin, not role — system-generated segments are immutable."},"description":{"type":"string","description":"Human-readable description of the segment","nullable":true},"status":{"description":"Segment status: 'new' means the segment was just created and metrics data is not yet available; 'completed' means data has been populated and the segment can be used with daily metrics endpoints.","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"filters":{"readOnly":true,"description":"The segment's filter configuration, in the same format accepted by create_segment. Excludes the provider filter (already shown in the provider field)."},"monthly_budget":{"type":"number","description":"User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.","nullable":true}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Create a new segment

> Creates a new segment with the specified filter configuration. The provider filter is injected automatically — only include filters for resource attributes you want to narrow on.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments":{"post":{"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSegmentArgs"}}}},"tags":["Segments (Beta)"],"summary":"Create a new segment","description":"Creates a new segment with the specified filter configuration. The provider filter is injected automatically — only include filters for resource attributes you want to narrow on."}}},"components":{"schemas":{"Segment":{"type":"object","properties":{"id":{"type":"string","description":"Unique segment identifier"},"name":{"type":"string","description":"Segment name"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"is_system_generated":{"type":"boolean","description":"True if this segment was created automatically by the system (e.g. the provider-resources default segment). Describes origin, not role — system-generated segments are immutable."},"description":{"type":"string","description":"Human-readable description of the segment","nullable":true},"status":{"description":"Segment status: 'new' means the segment was just created and metrics data is not yet available; 'completed' means data has been populated and the segment can be used with daily metrics endpoints.","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"filters":{"readOnly":true,"description":"The segment's filter configuration, in the same format accepted by create_segment. Excludes the provider filter (already shown in the provider field)."},"monthly_budget":{"type":"number","description":"User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.","nullable":true}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"CreateSegmentArgs":{"type":"object","properties":{"name":{"type":"string","description":"Segment name"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"filters":{"type":"object","description":"Filter tree using and/or/not combinators with field/op/value leaves. Use `has` on `tags` with nested key/value filters for tag matches. The provider filter is injected automatically.","additionalProperties":{}},"description":{"type":"string","default":null,"description":"Human-readable description","nullable":true}},"required":["filters","name","provider"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get segment details

> Returns details for a single segment including monthly metrics.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Segments (Beta)","description":"Segment management endpoints"}],"paths":{"/beta/v1/org/{org_id}/segments/{segment_id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Segments (Beta)"],"summary":"Get segment details","description":"Returns details for a single segment including monthly metrics."}}},"components":{"schemas":{"Segment":{"type":"object","properties":{"id":{"type":"string","description":"Unique segment identifier"},"name":{"type":"string","description":"Segment name"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"is_system_generated":{"type":"boolean","description":"True if this segment was created automatically by the system (e.g. the provider-resources default segment). Describes origin, not role — system-generated segments are immutable."},"description":{"type":"string","description":"Human-readable description of the segment","nullable":true},"status":{"description":"Segment status: 'new' means the segment was just created and metrics data is not yet available; 'completed' means data has been populated and the segment can be used with daily metrics endpoints.","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"filters":{"readOnly":true,"description":"The segment's filter configuration, in the same format accepted by create_segment. Excludes the provider filter (already shown in the provider field)."},"monthly_budget":{"type":"number","description":"User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.","nullable":true}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Invoices (Beta)

Invoice history endpoints

## List invoices

> Returns all invoices for the organization, most recent first. Invoices are generated monthly once cloud provider bills are finalized and are the source of truth for Archera premiums and rebates. Per-term breakdowns are only included on the detail endpoint.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Invoices (Beta)","description":"Invoice history endpoints"}],"paths":{"/beta/v1/org/{org_id}/invoices":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceList"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Invoices (Beta)"],"summary":"List invoices","description":"Returns all invoices for the organization, most recent first. Invoices are generated monthly once cloud provider bills are finalized and are the source of truth for Archera premiums and rebates. Per-term breakdowns are only included on the detail endpoint."}}},"components":{"schemas":{"InvoiceList":{"type":"object","properties":{"id":{"type":"string","description":"Invoice identifier"},"year":{"type":"integer","description":"Invoice year"},"month":{"type":"integer","description":"Invoice month (1-12)"},"invoice_date":{"type":"string","format":"date","description":"Invoice date (first of the month)"},"commitment_financials_invoice_month":{"description":"Aggregated list-price figures across all providers for the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items/sections); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"premium_billing":{"description":"Premium waterfall across all providers — list_price, discount, credits_applied, and the charged amount. `premium_billing.charged` is the answer to 'how much did I pay Archera this month' — not the archera_premium inside commitment_financials_invoice_month, which is list-price.","allOf":[{"$ref":"#/components/schemas/PremiumBilling"}]},"total_cloud_bill":{"readOnly":true,"description":"Total cloud provider bill across all providers, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)."},"sections":{"description":"Per-provider breakdown of the invoice","type":"array","items":{"$ref":"#/components/schemas/InvoiceSectionList"}}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"PremiumBilling":{"type":"object","properties":{"charged":{"type":"number","description":"Premium actually charged on the bill — post-discount, post-credits. Headline: 'how much the user paid Archera for this billing scope.'"},"list_price":{"type":"number","description":"Pre-discount, pre-credits premium. Starting point of the billing waterfall."},"discount":{"description":"Discount applied to the list price (rate and precomputed amount).","allOf":[{"$ref":"#/components/schemas/PremiumDiscount"}]},"credits_applied":{"type":"number","description":"Credits (from rebates or other sources) applied to reduce the premium."}},"additionalProperties":false},"PremiumDiscount":{"type":"object","properties":{"rate":{"type":"number","description":"Discount rate (0-1, usually 0)."},"amount":{"type":"number","description":"Dollars removed by the discount. Equals list_price * rate."}},"additionalProperties":false},"InvoiceSectionList":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"commitment_financials_invoice_month":{"description":"Aggregated list-price figures for this provider over the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"premium_billing":{"description":"Premium waterfall for this provider — list_price, discount, credits_applied, and the charged amount that hits the bill. `charged` is the answer to 'what did the user actually pay Archera for this provider' — not the archera_premium inside commitment_financials_invoice_month, which is list-price.","allOf":[{"$ref":"#/components/schemas/PremiumBilling"}]},"total_cloud_bill":{"type":"number","description":"Total cloud provider bill for this period, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get invoice by year and month

> Returns a single invoice for the specified year and month. Invoices are the source of truth for Archera fees and premiums charged during each billing cycle.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Invoices (Beta)","description":"Invoice history endpoints"}],"paths":{"/beta/v1/org/{org_id}/invoices/{year}/{month}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Invoices (Beta)"],"summary":"Get invoice by year and month","description":"Returns a single invoice for the specified year and month. Invoices are the source of truth for Archera fees and premiums charged during each billing cycle."}}},"components":{"schemas":{"Invoice":{"type":"object","properties":{"id":{"type":"string","description":"Invoice identifier"},"year":{"type":"integer","description":"Invoice year"},"month":{"type":"integer","description":"Invoice month (1-12)"},"invoice_date":{"type":"string","format":"date","description":"Invoice date (first of the month)"},"commitment_financials_invoice_month":{"description":"Aggregated list-price figures across all providers for the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items/sections); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"premium_billing":{"description":"Premium waterfall across all providers — list_price, discount, credits_applied, and the charged amount. `premium_billing.charged` is the answer to 'how much did I pay Archera this month' — not the archera_premium inside commitment_financials_invoice_month, which is list-price.","allOf":[{"$ref":"#/components/schemas/PremiumBilling"}]},"total_cloud_bill":{"readOnly":true,"description":"Total cloud provider bill across all providers, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)."},"sections":{"description":"Per-provider breakdown of the invoice","type":"array","items":{"$ref":"#/components/schemas/InvoiceSection"}},"by_term":{"type":"array","description":"Invoice-month metrics across all providers broken down by contract term (from `InvoiceLineItem.contract_term`). GRI labels = Archera Guaranteed; Commitment labels = native cloud commitments. Sum across GRI labels for the insured view, across Commitment labels for the uninsured view.","items":{"$ref":"#/components/schemas/InvoiceBreakdown"}},"by_type":{"type":"array","description":"Invoice-month metrics across all providers broken down by commitment type (e.g. 'Compute', 'EC2Instance', 'RDS').","items":{"$ref":"#/components/schemas/InvoiceBreakdown"}}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"PremiumBilling":{"type":"object","properties":{"charged":{"type":"number","description":"Premium actually charged on the bill — post-discount, post-credits. Headline: 'how much the user paid Archera for this billing scope.'"},"list_price":{"type":"number","description":"Pre-discount, pre-credits premium. Starting point of the billing waterfall."},"discount":{"description":"Discount applied to the list price (rate and precomputed amount).","allOf":[{"$ref":"#/components/schemas/PremiumDiscount"}]},"credits_applied":{"type":"number","description":"Credits (from rebates or other sources) applied to reduce the premium."}},"additionalProperties":false},"PremiumDiscount":{"type":"object","properties":{"rate":{"type":"number","description":"Discount rate (0-1, usually 0)."},"amount":{"type":"number","description":"Dollars removed by the discount. Equals list_price * rate."}},"additionalProperties":false},"InvoiceSection":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"commitment_financials_invoice_month":{"description":"Aggregated list-price figures for this provider over the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"premium_billing":{"description":"Premium waterfall for this provider — list_price, discount, credits_applied, and the charged amount that hits the bill. `charged` is the answer to 'what did the user actually pay Archera for this provider' — not the archera_premium inside commitment_financials_invoice_month, which is list-price.","allOf":[{"$ref":"#/components/schemas/PremiumBilling"}]},"total_cloud_bill":{"type":"number","description":"Total cloud provider bill for this period, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)"},"by_term":{"type":"array","description":"This provider section's invoice-month metrics broken down by contract term (from `InvoiceLineItem.contract_term`). GRI labels = Archera Guaranteed; Commitment labels = native cloud commitments. Sum across GRI labels for the insured view, across Commitment labels for the uninsured view.","items":{"$ref":"#/components/schemas/InvoiceBreakdown"}},"by_type":{"type":"array","description":"This provider section's invoice-month metrics broken down by commitment type (e.g. 'Compute', 'EC2Instance', 'RDS').","items":{"$ref":"#/components/schemas/InvoiceBreakdown"}}},"additionalProperties":false},"InvoiceBreakdown":{"type":"object","properties":{"label":{"type":"string","description":"Group label"},"count":{"type":"integer","description":"Number of line items in this group"},"commitment_financials_invoice_month":{"description":"Aggregated list-price invoice-month financials for this group. commitment_cost.breakdown.archera_premium is list-price, matching line-item/section/invoice aggregation.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get invoice line items

> Returns all line items for the specified invoice, showing per-commitment charges, savings, premiums, and rebates.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Invoices (Beta)","description":"Invoice history endpoints"}],"paths":{"/beta/v1/org/{org_id}/invoices/{year}/{month}/line-items":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLineItem"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Invoices (Beta)"],"summary":"Get invoice line items","description":"Returns all line items for the specified invoice, showing per-commitment charges, savings, premiums, and rebates."}}},"components":{"schemas":{"InvoiceLineItem":{"type":"object","properties":{"id":{"type":"string","description":"Line item identifier"},"commitment_id":{"type":"string","description":"Associated commitment identifier"},"commitment":{"description":"Full commitment details (identity, dates, guarantee info, region/instance info, contract term). Metrics (utilization/financials) aren't included here — this invoice line item has its own financials.","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"utilization":{"type":"number","description":"Average utilization for this commitment during the invoice period (0-1)"},"contract_term":{"description":"Contract term of the commitment as it applied during this invoice's billing month — reflects the guarantee lock-in in effect at bill time. Prefer this over `commitment.contract_term`, which reflects the commitment's current term and may have shifted since (e.g. lock-in rolled over, guarantee changed).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"commitment_financials_invoice_month":{"description":"Actual dollars billed for this line item over the invoice's calendar month. commitment_cost.breakdown.archera_premium is this line item's list-price premium — invoice-wide discount/credits don't attribute per-commitment, so there's no line-item charged value. For the real charged premium on the bill and the full waterfall (list_price, discount, credits), see the parent section's or invoice's `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Cost Explorer (Beta)

Total cloud spend exploration

## Explore total cloud spend

> Returns total cloud spend over a date range, optionally grouped by service, account, or region. Includes all cost types (not just reservable). Data comes from cloud provider Cost Explorer APIs.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Cost Explorer (Beta)","description":"Total cloud spend exploration"}],"paths":{"/beta/v1/org/{org_id}/cost-explorer":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"segment_id","description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false},{"in":"query","name":"start_date","description":"Start date (YYYY-MM-DD)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"end_date","description":"End date (YYYY-MM-DD, exclusive)","schema":{"type":"string","format":"date"},"required":true},{"in":"query","name":"group_by","description":"Dimension to group costs by: 'service', 'account', or 'region'. If omitted, returns total spend without grouping.","schema":{"default":null,"type":"string","enum":["service","account","region",null],"nullable":true},"required":false},{"in":"query","name":"granularity","description":"Time granularity: 'daily' or 'monthly' (default 'daily')","schema":{"default":"daily","type":"string","enum":["daily","monthly"]},"required":false},{"in":"query","name":"metric","description":"Cost metric to use. 'amortized' (default): includes upfront costs spread over commitment term. 'unblended' (AWS only): actual charges as they appear on the bill. 'actual' (Azure/GCP only): equivalent to unblended for Azure and GCP.","schema":{"default":"amortized","type":"string","enum":["amortized","unblended","actual"]},"required":false},{"in":"query","name":"top_n","description":"Return only the top N groups by cost, with remaining groups combined into 'Other'. If omitted, returns all groups.","schema":{"type":"integer","default":null,"minimum":1,"nullable":true},"required":false},{"in":"query","name":"include_discounts_and_credits","description":"Include credits, refunds, and enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements) in the cost data. Default false (shows spend before credits and discounts).","schema":{"type":"boolean","default":false},"required":false},{"in":"query","name":"include_time_series","description":"Include time-series data points for each group. Default true. Set to false for compact summary-only responses.","schema":{"type":"boolean","default":true},"required":false},{"in":"query","name":"filter","description":"Pre-query filter applied before grouping. Uses field/op/value with and/or/not combinators. Supported operators: = (equals), != (not equals), in (list of values). Available fields: service, account_id, region, instance_type, instance_family, operating_system, tenancy. Example: {\"field\": \"service\", \"op\": \"!=\", \"value\": \"Tax\"}","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostExplorerResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Cost Explorer (Beta)"],"summary":"Explore total cloud spend","description":"Returns total cloud spend over a date range, optionally grouped by service, account, or region. Includes all cost types (not just reservable). Data comes from cloud provider Cost Explorer APIs."}}},"components":{"schemas":{"CostExplorerResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"total_cost":{"type":"number","description":"Total cost across all groups over the effective date range. Headline 'cost' — the answer to 'what did I spend.' Sum of groups[*].total_cost."},"groups":{"type":"array","description":"Cost groups, sorted by total spend descending","items":{"$ref":"#/components/schemas/CostExplorerGroup"}}},"additionalProperties":false},"CostExplorerGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (e.g. service name, account ID, region)"},"total_cost":{"type":"number","description":"Total cost for this group over the entire period"},"percentage":{"type":"number","description":"This group's share of total spend (0-1)"},"data":{"type":"array","default":null,"description":"Time-series data points for this group. Only included when include_time_series=true.","items":{"$ref":"#/components/schemas/CostExplorerDataPoint"},"nullable":true}},"additionalProperties":false},"CostExplorerDataPoint":{"type":"object","properties":{"date":{"type":"string","description":"Date or month label for this data point"},"cost":{"type":"number","description":"Cost for this period"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get available cost-explorer filter fields and values

> Returns the valid filter fields and their possible values for building cost-explorer filter parameters. Field names in the response can be used directly as the 'field' value in filter expressions.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Cost Explorer (Beta)","description":"Total cloud spend exploration"}],"paths":{"/beta/v1/org/{org_id}/cost-explorer/filters":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostExplorerFilters"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Cost Explorer (Beta)"],"summary":"Get available cost-explorer filter fields and values","description":"Returns the valid filter fields and their possible values for building cost-explorer filter parameters. Field names in the response can be used directly as the 'field' value in filter expressions."}}},"components":{"schemas":{"CostExplorerFilters":{"type":"object","properties":{"service":{"type":"array","description":"Available cloud service names","items":{"type":"string"}},"account_id":{"type":"array","description":"Available cloud account IDs","items":{"type":"string"}},"region":{"type":"array","description":"Available cloud regions","items":{"type":"string"}},"instance_family":{"type":"array","description":"Available instance families (AWS only)","items":{"type":"string"}},"operating_system":{"type":"array","description":"Available operating systems (AWS only)","items":{"type":"string"}},"tenancy":{"type":"array","description":"Available tenancy types (AWS only)","items":{"type":"string"}}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Exchanges (Beta)

Agent-friendly commitment exchange endpoints

## Get Azure exchange recommendations

> Returns Azure reservation exchange recommendations from two sources: plan-derived exchanges that use a commitment plan as the purchase side, and non-plan-derived exchanges that replace eligible 1-year native reservations with same-SKU 1-year GRI purchases backed by 3-year offers. Plan-derived recommendations use either explicit commitments or detected underutilized commitments as the return side. Currently only provider=azure is supported. When plan\_id is omitted, the endpoint prefers the latest calculated 'Recommended RIs Only' default plan for the provider-resources segment (a twin of the Recommended plan without savings plans, which cannot be exchanged), falling back to the same Recommended default plan as GET /commitment-plans/recommended when that plan does not exist yet. Returned-commitment utilization and financials use a fixed 3-day lookback. Explicit commitments without DailyUtilization rows in that lookback are excluded.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Exchanges (Beta)","description":"Agent-friendly commitment exchange endpoints"}],"paths":{"/beta/v1/org/{org_id}/exchanges/recommendations":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"plan_id","description":"Optional commitment plan ID to use for plan-derived exchange purchases. When omitted, the endpoint prefers the latest calculated 'Recommended RIs Only' default plan for the provider-resources segment — a twin of the Recommended plan without savings plans, which cannot be exchanged — falling back to the same Recommended default plan selected by GET /commitment-plans/recommended when that plan does not exist yet. Responses may also include non-plan-derived native-to-GRI exchanges.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false},{"in":"query","name":"commitment_ids","description":"Optional explicit Azure commitment IDs to consider returning. When omitted, the exchanger detects underutilized exchange candidates from the default 3-day DailyUtilization lookback. Explicit commitments without utilization rows in that lookback are excluded. Mutually exclusive with plan_id.","schema":{"type":"array","default":null,"items":{"type":"string","format":"uuid"},"nullable":true},"required":false,"explode":true,"style":"form"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeRecommendationsResponse"}}}},"204":{"description":"No Content"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Exchanges (Beta)"],"summary":"Get Azure exchange recommendations","description":"Returns Azure reservation exchange recommendations from two sources: plan-derived exchanges that use a commitment plan as the purchase side, and non-plan-derived exchanges that replace eligible 1-year native reservations with same-SKU 1-year GRI purchases backed by 3-year offers. Plan-derived recommendations use either explicit commitments or detected underutilized commitments as the return side. Currently only provider=azure is supported. When plan_id is omitted, the endpoint prefers the latest calculated 'Recommended RIs Only' default plan for the provider-resources segment (a twin of the Recommended plan without savings plans, which cannot be exchanged), falling back to the same Recommended default plan as GET /commitment-plans/recommended when that plan does not exist yet. Returned-commitment utilization and financials use a fixed 3-day lookback. Explicit commitments without DailyUtilization rows in that lookback are excluded."}}},"components":{"schemas":{"ExchangeRecommendationsResponse":{"type":"object","properties":{"current_utilization_lookback_days":{"type":"integer","description":"Number of trailing days of DailyUtilization used for returned-commitment utilization and financials."},"data":{"type":"array","description":"Azure exchange recommendations.","items":{"$ref":"#/components/schemas/ExchangeRecommendation"}}},"required":["current_utilization_lookback_days","data"],"additionalProperties":false},"ExchangeRecommendation":{"type":"object","properties":{"purchase_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value of the purchase side."},"returned_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value returned by the exchange."},"additional_lifetime_commitment":{"type":"number","description":"Purchase lifetime commitment minus returned lifetime commitment. Azure exchange policy requires this to be non-negative."},"purchase":{"$ref":"#/components/schemas/ExchangePurchase"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeReturn"}},"purchase_commitment_financials_monthly_rate":{"description":"Purchase-side monthly-rate financials.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"returned_commitment_financials_monthly_rate":{"description":"Returned commitments' rolled-up monthly-rate financials for the selected integer return quantities. Cost comes from DailyUtilization commitment cost, and savings are computed after assigning as much utilization as possible to the quantity that remains committed. Rebate and Archera premium are excluded from exchange recommendations and are not included in net savings.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"returned_commitment_daily_utilizations":{"type":"array","description":"Daily whole-commitment utilization for the returned commitments, dollar weighted by each return's commitment cost. Use this for exchange-level utilization charts.","items":{"$ref":"#/components/schemas/ExchangeReturnedCommitmentDailyUtilization"}},"reason":{"type":"string","description":"Short human-readable reason this exchange was recommended, based on how the exchanger generated it.","nullable":true},"delta_vs_returned":{"description":"Purchase-side economics compared with returned-commitment economics. Monthly fields are purchase-side minus returned-side; purchase_upfront_cost is purchase-side one-time upfront only and is not netted. Purchase financials come from plan-amortized line item financials; returned financials come from DailyUtilization cost and covered usage for the selected integer return quantities, normalized to 730-hour monthly rates.","allOf":[{"$ref":"#/components/schemas/ExchangeRecommendationDelta"}]}},"required":["additional_lifetime_commitment","delta_vs_returned","purchase","purchase_commitment_financials_monthly_rate","purchase_lifetime_commitment","returned_commitment_daily_utilizations","returned_commitment_financials_monthly_rate","returned_lifetime_commitment","returns"],"additionalProperties":false},"ExchangePurchase":{"type":"object","properties":{"account_id":{"type":"string","description":"Target cloud account/subscription for the purchase.","nullable":true},"contract_term":{"description":"User-facing purchase commitment term. For leased/guaranteed purchases this is the lease lock-in term; for native purchases it is the offer duration.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease menu item attached to the purchase side, or null for native purchases.","nullable":true},"quantity":{"type":"integer","description":"Quantity of the Azure reservation to purchase."},"offer":{"description":"Azure reservation offer being purchased.","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"commitment_upfront_cost":{"type":"number","description":"One-time upfront dollars required at signing for the purchase side. NOT a monthly rate."},"commitment_financials_monthly_rate":{"description":"Purchase-side plan line item economics as 730-hour monthly rates.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","offer","quantity"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"ExchangeReturn":{"type":"object","properties":{"commitment":{"description":"Azure commitment proposed to return in the exchange.","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"quantity":{"type":"integer","description":"Quantity of this commitment proposed for return."},"remaining_lifetime_commitment":{"type":"number","description":"Remaining Azure commitment value returned for this commitment quantity. This is lifetime exchange value, not a monthly rate."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitment over the DailyUtilization period (0-1)."},"underutilized_commitment_cost":{"type":"number","description":"Estimated underutilized commitment cost over the DailyUtilization period. This is a period total, not a monthly rate."},"utilization_days":{"type":"integer","description":"Number of DailyUtilization days behind the utilization fields."},"reservation_resource_id":{"type":"string","description":"Azure reservation resource ID required by Azure exchange APIs."},"commitment_financials_monthly_rate":{"description":"Returned commitment economics as a 730-hour monthly rate for the selected integer return quantity. Cost comes from DailyUtilization commitment cost for the response period, scaled to the returned quantity. Savings are computed after assigning as much utilization as possible to the quantity that remains committed, so returned fully-utilized quantities can have positive savings and underutilized quantities have negative savings. Archera premium and rebate are excluded from exchange recommendations and are not included in net savings.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment","commitment_financials_monthly_rate","quantity","remaining_lifetime_commitment","reservation_resource_id","underutilized_commitment_cost","utilization","utilization_days"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"ExchangeReturnedCommitmentDailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"DailyUtilization date."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitments for this date (0-1), dollar weighted by each return's commitment cost."}},"required":["date","utilization"],"additionalProperties":false},"ExchangeRecommendationDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Purchase monthly net savings minus returned commitments' monthly net savings. Positive means the exchange purchase saves more per 730-hour month."},"monthly_commitment_cost":{"type":"number","description":"Purchase monthly commitment cost minus returned commitments' monthly commitment cost. Positive means more monthly commitment spend."},"purchase_upfront_cost":{"type":"number","description":"Purchase-side one-time upfront cost only. Not netted against returned commitments because returned financials are monthly-rate utilization actuals and have no upfront component. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","purchase_upfront_cost"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Apply Azure exchange recommendations

> Requests application of one Azure reservation exchange recommendation. The request body must contain the exact purchase-side offers and return-side commitments from the recommendation the user approved. Currently only provider=azure is supported.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Exchanges (Beta)","description":"Agent-friendly commitment exchange endpoints"}],"paths":{"/beta/v1/org/{org_id}/exchanges/recommendations/apply":{"post":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyExchangeRecommendationsResponse"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyExchangeRecommendationsArgs"}}}},"tags":["Exchanges (Beta)"],"summary":"Apply Azure exchange recommendations","description":"Requests application of one Azure reservation exchange recommendation. The request body must contain the exact purchase-side offers and return-side commitments from the recommendation the user approved. Currently only provider=azure is supported."}}},"components":{"schemas":{"ApplyExchangeRecommendationsResponse":{"type":"object","properties":{"status":{"type":"string","description":"Application status for the exchange recommendations."},"recommendation_count":{"type":"integer","description":"Number of exchange recommendations applied."}},"required":["recommendation_count","status"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"ApplyExchangeRecommendationsArgs":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"purchases":{"type":"array","minItems":1,"description":"Explicit purchase-side line items for one exchange recommendation.","items":{"$ref":"#/components/schemas/ApplyExchangePurchase"}},"returns":{"type":"array","minItems":1,"description":"Explicit return-side line items for one exchange recommendation.","items":{"$ref":"#/components/schemas/ApplyExchangeReturn"}}},"required":["provider","purchases","returns"],"additionalProperties":false},"ApplyExchangePurchase":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Azure reservation offer ID to purchase."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this offer to purchase."}},"required":["offer_id","quantity"],"additionalProperties":false},"ApplyExchangeReturn":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Existing Azure commitment ID to return."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this commitment to return."}},"required":["commitment_id","quantity"],"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Integrations (Beta)

Cloud provider integration endpoints

## List integrations

> Returns all active cloud provider integrations for the organization.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Integrations (Beta)","description":"Cloud provider integration endpoints"}],"paths":{"/beta/v1/org/{org_id}/integrations":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Integration"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Integrations (Beta)"],"summary":"List integrations","description":"Returns all active cloud provider integrations for the organization."}}},"components":{"schemas":{"Integration":{"type":"object","properties":{"id":{"type":"string","description":"Integration identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Integration name","nullable":true},"provider_organization_id":{"type":"string","description":"Cloud-provider organization/tenant identifier (AWS Organizations ID, Azure tenant ID, GCP organization ID).","nullable":true},"active":{"type":"boolean","description":"Whether this integration has active credentials"},"currency":{"type":"string","description":"Billing currency (e.g. 'USD')","nullable":true},"data_available_since":{"type":"string","format":"date-time","description":"Earliest date cost data is available from this integration","nullable":true},"data_available_until":{"type":"string","format":"date-time","description":"Latest date cost data is available from this integration","nullable":true}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get integration details

> Returns details for a single integration including its cloud accounts.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Integrations (Beta)","description":"Cloud provider integration endpoints"}],"paths":{"/beta/v1/org/{org_id}/integrations/{integration_id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Integrations (Beta)"],"summary":"Get integration details","description":"Returns details for a single integration including its cloud accounts."}}},"components":{"schemas":{"IntegrationDetail":{"type":"object","properties":{"id":{"type":"string","description":"Integration identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Integration name","nullable":true},"provider_organization_id":{"type":"string","description":"Cloud-provider organization/tenant identifier (AWS Organizations ID, Azure tenant ID, GCP organization ID).","nullable":true},"active":{"type":"boolean","description":"Whether this integration has active credentials"},"currency":{"type":"string","description":"Billing currency (e.g. 'USD')","nullable":true},"data_available_since":{"type":"string","format":"date-time","description":"Earliest date cost data is available from this integration","nullable":true},"data_available_until":{"type":"string","format":"date-time","description":"Latest date cost data is available from this integration","nullable":true},"accounts":{"readOnly":true,"description":"Cloud accounts associated with this integration"}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Resources (Beta)

Per-customer resource inventory — attribute filters, free-text search, and per-resource detail. Cross-references catalog SKUs via (catalog\_sku\_org\_id, catalog\_sku\_id).

## List filterable resource SKU attributes

> Returns the fields that can be used in the 'filter' parameter of the /resources/skus list endpoint, along with their types.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Resources (Beta)","description":"Per-customer resource inventory — attribute filters, free-text search, and per-resource detail. Cross-references catalog SKUs via (catalog_sku_org_id, catalog_sku_id)."}],"paths":{"/beta/v1/org/{org_id}/resources/skus/attributes":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BaseAttribute"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"List filterable resource SKU attributes","tags":["Resources (Beta)"],"description":"Returns the fields that can be used in the 'filter' parameter of the /resources/skus list endpoint, along with their types."}}},"components":{"schemas":{"BaseAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean","integer","float","date","datetime","time","currency","percent","string","enum","uuid","tags"]}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get valid values for a filterable resource SKU attribute

> Returns the distinct values for a given field, scoped to the same provider/segment/filter as the list endpoint. Use this to narrow refinements (e.g. ask for valid instance\_type values for a given service+region before issuing a list call) without paginating through SKU rows.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Resources (Beta)","description":"Per-customer resource inventory — attribute filters, free-text search, and per-resource detail. Cross-references catalog SKUs via (catalog_sku_org_id, catalog_sku_id)."}],"paths":{"/beta/v1/org/{org_id}/resources/skus/attributes/{field}":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"segment_id","description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false},{"in":"query","name":"search","description":"Text search across resource id, name, provider_resource_id, account ids, and the curated SKU attribute fields (service, region_code, instance_type, etc.). Use for fuzzy id/name lookups; use `filter` for structured queries.","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on scalar fields; `has` on `tags` with nested key/value filters; `>`, `>=`, `<`, `<=` on numeric/percent fields (`total_cost`, `ondemand_cost`, `gross_savings`, `coverage`, `uptime`) and date fields (`usage_start`, `usage_end`). Examples: {\"and\": [{\"field\": \"service\", \"op\": \"=\", \"value\": \"Amazon Elastic Compute Cloud - Compute\"}, {\"field\": \"instance_type\", \"op\": \"=\", \"value\": \"m5.large\"}]} — categorical; {\"field\": \"tags\", \"op\": \"has\", \"value\": {\"and\": [{\"field\": \"key\", \"op\": \"=\", \"value\": \"Environment\"}, {\"field\": \"value\", \"op\": \"=\", \"value\": \"production\"}]}} — tag match; {\"field\": \"total_cost\", \"op\": \">\", \"value\": 1000} — spend > $1k; {\"field\": \"coverage\", \"op\": \"<\", \"value\": 0.5} — under-covered. Call /resources/skus/attributes for filterable fields and /resources/skus/attributes/<field> for valid categorical values within the current scope. Trailing-30-day spend/usage aggregates pair well with `order_by` for 'highest cost in service X' / 'lowest uptime' style queries.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by. Includes the trailing-30-day spend/usage aggregates (`total_cost`, `ondemand_cost`, `gross_savings`, `coverage`, `uptime`).","schema":{"type":"string","default":"id","enum":["id","usage_start","usage_end","instance_type","service","region_code","total_cost","ondemand_cost","gross_savings","coverage","uptime"]},"required":false},{"in":"query","name":"desc","description":"Sort descending","schema":{"type":"boolean","default":false},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attribute"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Get valid values for a filterable resource SKU attribute","tags":["Resources (Beta)"],"description":"Returns the distinct values for a given field, scoped to the same provider/segment/filter as the list endpoint. Use this to narrow refinements (e.g. ask for valid instance_type values for a given service+region before issuing a list call) without paginating through SKU rows."}}},"components":{"schemas":{"Attribute":{"oneOf":[{"$ref":"#/components/schemas/BooleanAttribute"},{"$ref":"#/components/schemas/UUIDAttribute"},{"$ref":"#/components/schemas/StringAttribute"},{"$ref":"#/components/schemas/IntegerAttribute"},{"$ref":"#/components/schemas/FloatAttribute"},{"$ref":"#/components/schemas/CurrencyAttribute"},{"$ref":"#/components/schemas/PercentAttribute"},{"$ref":"#/components/schemas/DateTimeAttribute"},{"$ref":"#/components/schemas/DateAttribute"},{"$ref":"#/components/schemas/TimeAttribute"},{"$ref":"#/components/schemas/EnumAttribute"},{"$ref":"#/components/schemas/TagsAttribute"}],"discriminator":{"propertyName":"type","mapping":{"boolean":"#/components/schemas/BooleanAttribute","uuid":"#/components/schemas/UUIDAttribute","string":"#/components/schemas/StringAttribute","integer":"#/components/schemas/IntegerAttribute","float":"#/components/schemas/FloatAttribute","currency":"#/components/schemas/CurrencyAttribute","percent":"#/components/schemas/PercentAttribute","datetime":"#/components/schemas/DateTimeAttribute","date":"#/components/schemas/DateAttribute","time":"#/components/schemas/TimeAttribute","enum":"#/components/schemas/EnumAttribute","tags":"#/components/schemas/TagsAttribute"}}},"BooleanAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false},"UUIDAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["uuid"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"StringAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["string"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"IntegerAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["integer"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"FloatAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["float"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"CurrencyAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["currency"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"PercentAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["percent"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateTimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["datetime"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["date"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"TimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["time"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"EnumAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["enum"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"TagsAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["tags"],"readOnly":true},"tags":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## List resource SKU rows in the customer's environment

> Returns ResourceSKU rows (resource x SKU x time-window) scoped to the specified provider segment and the org's current attribution. Each row is one observation period of a resource running with a specific SKU; the same underlying resource may appear multiple times if it changed SKUs. Cross-reference catalog SKUs via (catalog\_sku\_org\_id, catalog\_sku\_id). \`X-Pagination\` is navigation-only: it always includes \`page\` and \`first\_page\`, and adds \`previous\_page\` and \`next\_page\` when available. This avoids a slow Snowflake COUNT(\*) on large customers.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Resources (Beta)","description":"Per-customer resource inventory — attribute filters, free-text search, and per-resource detail. Cross-references catalog SKUs via (catalog_sku_org_id, catalog_sku_id)."}],"paths":{"/beta/v1/org/{org_id}/resources/skus":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"segment_id","description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","schema":{"type":"string","format":"uuid","default":null,"nullable":true},"required":false},{"in":"query","name":"search","description":"Text search across resource id, name, provider_resource_id, account ids, and the curated SKU attribute fields (service, region_code, instance_type, etc.). Use for fuzzy id/name lookups; use `filter` for structured queries.","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on scalar fields; `has` on `tags` with nested key/value filters; `>`, `>=`, `<`, `<=` on numeric/percent fields (`total_cost`, `ondemand_cost`, `gross_savings`, `coverage`, `uptime`) and date fields (`usage_start`, `usage_end`). Examples: {\"and\": [{\"field\": \"service\", \"op\": \"=\", \"value\": \"Amazon Elastic Compute Cloud - Compute\"}, {\"field\": \"instance_type\", \"op\": \"=\", \"value\": \"m5.large\"}]} — categorical; {\"field\": \"tags\", \"op\": \"has\", \"value\": {\"and\": [{\"field\": \"key\", \"op\": \"=\", \"value\": \"Environment\"}, {\"field\": \"value\", \"op\": \"=\", \"value\": \"production\"}]}} — tag match; {\"field\": \"total_cost\", \"op\": \">\", \"value\": 1000} — spend > $1k; {\"field\": \"coverage\", \"op\": \"<\", \"value\": 0.5} — under-covered. Call /resources/skus/attributes for filterable fields and /resources/skus/attributes/<field> for valid categorical values within the current scope. Trailing-30-day spend/usage aggregates pair well with `order_by` for 'highest cost in service X' / 'lowest uptime' style queries.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by. Includes the trailing-30-day spend/usage aggregates (`total_cost`, `ondemand_cost`, `gross_savings`, `coverage`, `uptime`).","schema":{"type":"string","default":"id","enum":["id","usage_start","usage_end","instance_type","service","region_code","total_cost","ondemand_cost","gross_savings","coverage","uptime"]},"required":false},{"in":"query","name":"desc","description":"Sort descending","schema":{"type":"boolean","default":false},"required":false},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ResourceSKUWithMetrics"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Resources (Beta)"],"summary":"List resource SKU rows in the customer's environment","description":"Returns ResourceSKU rows (resource x SKU x time-window) scoped to the specified provider segment and the org's current attribution. Each row is one observation period of a resource running with a specific SKU; the same underlying resource may appear multiple times if it changed SKUs. Cross-reference catalog SKUs via (catalog_sku_org_id, catalog_sku_id). `X-Pagination` is navigation-only: it always includes `page` and `first_page`, and adds `previous_page` and `next_page` when available. This avoids a slow Snowflake COUNT(*) on large customers."}}},"components":{"schemas":{"ResourceSKUWithMetrics":{"type":"object","properties":{"id":{"type":"string","description":"Composite ResourceSKU id — `<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`. Pass directly to `/resources/skus/<id>` for detail; do not parse it client-side."},"resource_id":{"type":"string","format":"uuid","description":"Underlying Resource id. Stable across SKU/time variants of the same resource — multiple ResourceSKU rows can share a `resource_id` when the same resource ran with different SKUs over its lifetime."},"catalog_sku_id":{"type":"string","format":"uuid","description":"Join key into `/catalog/skus/<id>` for the public SKU record."},"catalog_sku_org_id":{"type":"string","description":"Org id that owns the catalog SKU — public-catalog SKUs use the public org id; custom-priced SKUs use the customer's org id."},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"provider_resource_id":{"type":"string","description":"Provider's id for the resource (AWS ARN, Azure resource ID, GCP resource name). This is the canonical identifier the user sees in the cloud console."},"provider_sku_id":{"type":"string","description":"Provider's own SKU identifier","nullable":true},"name":{"type":"string","description":"Resource name (Resource.name) — the user-applied label, e.g. 'prod-db-1'. Distinct from `sku_name`, which is the catalog SKU's display name.","nullable":true},"sku_name":{"type":"string","description":"Catalog SKU display name (e.g. 'Amazon EC2 Instance', 'Amazon Aurora PostgreSQL Cluster'). Useful as a fallback label when `instance_type_family` and `usage_type` are both null. Distinct from `name` (the resource's user-applied label).","nullable":true},"integration_id":{"type":"string","description":"Integration this resource belongs to"},"billing_account_id":{"type":"string","description":"Provider billing/management account id","nullable":true},"sub_account_id":{"type":"string","description":"Provider account id that owns/created the resource","nullable":true},"resource_group":{"type":"string","nullable":true},"is_spot":{"type":"boolean","nullable":true},"availability_zone":{"type":"string","nullable":true},"service":{"type":"string","description":"Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')","nullable":true},"provider_service":{"type":"string","description":"Provider service code (e.g. 'AmazonEC2')","nullable":true},"family":{"type":"string","description":"Product family (e.g. 'Compute Instance')","nullable":true},"region_code":{"type":"string","description":"Region code (e.g. 'us-east-1')","nullable":true},"full_region_name":{"type":"string","description":"Full region name (e.g. 'US East (N. Virginia)')","nullable":true},"instance_type":{"type":"string","nullable":true},"instance_type_family":{"type":"string","nullable":true},"usage_type":{"type":"string","description":"Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items.","nullable":true},"operation":{"type":"string","description":"Provider billing operation code (e.g. 'RunInstances:0002')","nullable":true},"operating_system":{"type":"string","nullable":true},"tenancy":{"type":"string","nullable":true},"database_engine":{"type":"string","nullable":true},"database_edition":{"type":"string","nullable":true},"cache_engine":{"type":"string","nullable":true},"is_multi_az":{"type":"boolean","nullable":true},"is_current_generation":{"type":"boolean","nullable":true},"license_model":{"type":"string","nullable":true},"pre_installed_sw":{"type":"string","nullable":true},"processor_architecture":{"type":"string","nullable":true},"is_reservable":{"type":"boolean","description":"Whether the SKU this resource is running has at least one reserved-term offering. Reservability is a property of the SKU, not the resource.","nullable":true},"is_byol":{"type":"boolean","description":"Whether the SKU is a Bring-Your-Own-License variant. Currently set for AWS RDS BYOL only; false elsewhere.","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the SKU is eligible for instance-size flexibility under reserved offerings (provider+service-specific rules — see `is_flexible` on the ResourceSKU model).","nullable":true},"is_serverless":{"type":"boolean","description":"Whether the SKU represents serverless usage.","nullable":true},"vcpu":{"type":"number","nullable":true},"memory":{"type":"number","description":"Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.","nullable":true},"ondemand_usage_unit":{"type":"string","nullable":true},"ondemand_usage_price":{"type":"number","description":"On-demand unit price in `price_currency`. List price from the catalog — this is NOT the user's actual spend for this resource (see ResourceSKUWithMetricsSchema's `total_cost` or /cost-explorer for that).","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_start":{"type":"string","format":"date-time","description":"Start of the period during which the resource was observed running this SKU. A resource that switched SKUs (e.g. instance-type resize) will have multiple ResourceSKU rows with disjoint `[usage_start, usage_end]` windows."},"usage_end":{"type":"string","format":"date-time","description":"End of the period during which the resource was observed running this SKU. Within ~2 days of now generally indicates the resource is currently active with this SKU."},"tags":{"type":"object","description":"Merged provider + user tags (user tags take precedence). Empty when the resource has no tags. Use the `untagged` filter to find resources with no tags at all.","additionalProperties":{"type":"string"},"nullable":true},"total_cost":{"type":"number","description":"Trailing-30-day total spend on this resource — what the user actually paid, summing the on-demand, spot, and commitment-covered portions. Reflects actuals already incurred under existing commitments, NOT a projection. Zero for resources not active in the last month.","nullable":true},"ondemand_cost":{"type":"number","description":"Trailing-30-day on-demand-priced portion of `total_cost` — i.e. spend that wasn't covered by a commitment or run as spot. NOT the counterfactual 'what it would have cost at on-demand prices' (that's `if_all_ondemand_cost`).","nullable":true},"gross_savings":{"type":"number","description":"Trailing-30-day savings already realized on this resource vs the on-demand baseline (`if_all_ondemand_cost - total_cost`). Actuals from existing commitments — NOT a projection of what a candidate plan would save. Per-row clamped at zero, so summing this across resources never goes negative. Archera premium is NOT subtracted on this endpoint (premium isn't attributed per resource here); for portfolio-level net savings see /commitments/metrics.","nullable":true},"if_all_ondemand_cost":{"readOnly":true,"description":"Trailing-30-day on-demand counterfactual — what `total_cost` would be if every hour of usage ran at on-demand prices. Equals `total_cost + gross_savings`. Headline baseline for 'how much is this commitment-covered resource saving me'."},"coverage":{"type":"number","description":"Trailing-30-day spend-based fraction of this resource's usage covered by ALL existing commitments (0-1). At this single-SKU granularity, the usage-unit and spend ratios are equivalent. Actuals — the BEFORE picture relative to any candidate plan. When nested inside a commitment plan's covered-resources response, this is distinct from per-match `projected_coverage` (the AFTER picture for that plan).","nullable":true},"uptime":{"type":"number","description":"Trailing-30-day fraction of time the resource was running (0-1). Null for non-running SKU types (storage, data transfer, etc.). Useful for rightsizing flags — low uptime on a large instance is a candidate for downsizing or termination.","nullable":true}},"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get a single resource SKU row's full detail

> Returns the full ResourceSKU record — list-view fields plus hardware specs, the raw catalog attribute blob, and SKU lifecycle dates. The id is the composite \`\<resource\_id>|\<catalog\_sku\_org\_id>|\<catalog\_sku\_id>\` returned by the list endpoint; pass it through verbatim. Scope: org + current attribution + the org's integrations — intentionally NOT narrowed by segment, unlike the list endpoint. Detail is an id-based fetch, not a browse query, so once a row's id is known it resolves regardless of which segment surfaced it. The asymmetry is one-directional: any row visible in the list (segment-scoped) is also visible here (org-scoped), so the list-then-detail flow never 404s on scope alone.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Resources (Beta)","description":"Per-customer resource inventory — attribute filters, free-text search, and per-resource detail. Cross-references catalog SKUs via (catalog_sku_org_id, catalog_sku_id)."}],"paths":{"/beta/v1/org/{org_id}/resources/skus/{resource_sku_id}":{"get":{"parameters":[{"in":"query","name":"expand","description":"Optional fields to populate. `covering_commitments` returns the per-CUD breakdown of which commitments covered this resource's usage in the requested period. Omit to keep typical detail calls scan-free.","schema":{"type":"array","items":{"type":"string","enum":["covering_commitments"]}},"required":false,"explode":true,"style":"form"},{"in":"query","name":"start_date","description":"Start date for expanded fields (YYYY-MM-DD). Defaults to 30 days ago.","schema":{"type":"string","format":"date","default":null,"nullable":true},"required":false},{"in":"query","name":"end_date","description":"End date for expanded fields (YYYY-MM-DD). Defaults to today.","schema":{"type":"string","format":"date","default":null,"nullable":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceSKUDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Resources (Beta)"],"summary":"Get a single resource SKU row's full detail","description":"Returns the full ResourceSKU record — list-view fields plus hardware specs, the raw catalog attribute blob, and SKU lifecycle dates. The id is the composite `<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>` returned by the list endpoint; pass it through verbatim. Scope: org + current attribution + the org's integrations — intentionally NOT narrowed by segment, unlike the list endpoint. Detail is an id-based fetch, not a browse query, so once a row's id is known it resolves regardless of which segment surfaced it. The asymmetry is one-directional: any row visible in the list (segment-scoped) is also visible here (org-scoped), so the list-then-detail flow never 404s on scope alone."}}},"components":{"schemas":{"ResourceSKUDetail":{"type":"object","properties":{"id":{"type":"string","description":"Composite ResourceSKU id — `<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`. Pass directly to `/resources/skus/<id>` for detail; do not parse it client-side."},"resource_id":{"type":"string","format":"uuid","description":"Underlying Resource id. Stable across SKU/time variants of the same resource — multiple ResourceSKU rows can share a `resource_id` when the same resource ran with different SKUs over its lifetime."},"catalog_sku_id":{"type":"string","format":"uuid","description":"Join key into `/catalog/skus/<id>` for the public SKU record."},"catalog_sku_org_id":{"type":"string","description":"Org id that owns the catalog SKU — public-catalog SKUs use the public org id; custom-priced SKUs use the customer's org id."},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"provider_resource_id":{"type":"string","description":"Provider's id for the resource (AWS ARN, Azure resource ID, GCP resource name). This is the canonical identifier the user sees in the cloud console."},"provider_sku_id":{"type":"string","description":"Provider's own SKU identifier","nullable":true},"name":{"type":"string","description":"Resource name (Resource.name) — the user-applied label, e.g. 'prod-db-1'. Distinct from `sku_name`, which is the catalog SKU's display name.","nullable":true},"sku_name":{"type":"string","description":"Catalog SKU display name (e.g. 'Amazon EC2 Instance', 'Amazon Aurora PostgreSQL Cluster'). Useful as a fallback label when `instance_type_family` and `usage_type` are both null. Distinct from `name` (the resource's user-applied label).","nullable":true},"integration_id":{"type":"string","description":"Integration this resource belongs to"},"billing_account_id":{"type":"string","description":"Provider billing/management account id","nullable":true},"sub_account_id":{"type":"string","description":"Provider account id that owns/created the resource","nullable":true},"resource_group":{"type":"string","nullable":true},"is_spot":{"type":"boolean","nullable":true},"availability_zone":{"type":"string","nullable":true},"service":{"type":"string","description":"Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')","nullable":true},"provider_service":{"type":"string","description":"Provider service code (e.g. 'AmazonEC2')","nullable":true},"family":{"type":"string","description":"Product family (e.g. 'Compute Instance')","nullable":true},"region_code":{"type":"string","description":"Region code (e.g. 'us-east-1')","nullable":true},"full_region_name":{"type":"string","description":"Full region name (e.g. 'US East (N. Virginia)')","nullable":true},"instance_type":{"type":"string","nullable":true},"instance_type_family":{"type":"string","nullable":true},"usage_type":{"type":"string","description":"Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items.","nullable":true},"operation":{"type":"string","description":"Provider billing operation code (e.g. 'RunInstances:0002')","nullable":true},"operating_system":{"type":"string","nullable":true},"tenancy":{"type":"string","nullable":true},"database_engine":{"type":"string","nullable":true},"database_edition":{"type":"string","nullable":true},"cache_engine":{"type":"string","nullable":true},"is_multi_az":{"type":"boolean","nullable":true},"is_current_generation":{"type":"boolean","nullable":true},"license_model":{"type":"string","nullable":true},"pre_installed_sw":{"type":"string","nullable":true},"processor_architecture":{"type":"string","nullable":true},"is_reservable":{"type":"boolean","description":"Whether the SKU this resource is running has at least one reserved-term offering. Reservability is a property of the SKU, not the resource.","nullable":true},"is_byol":{"type":"boolean","description":"Whether the SKU is a Bring-Your-Own-License variant. Currently set for AWS RDS BYOL only; false elsewhere.","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the SKU is eligible for instance-size flexibility under reserved offerings (provider+service-specific rules — see `is_flexible` on the ResourceSKU model).","nullable":true},"is_serverless":{"type":"boolean","description":"Whether the SKU represents serverless usage.","nullable":true},"vcpu":{"type":"number","nullable":true},"memory":{"type":"number","description":"Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.","nullable":true},"ondemand_usage_unit":{"type":"string","nullable":true},"ondemand_usage_price":{"type":"number","description":"On-demand unit price in `price_currency`. List price from the catalog — this is NOT the user's actual spend for this resource (see ResourceSKUWithMetricsSchema's `total_cost` or /cost-explorer for that).","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_start":{"type":"string","format":"date-time","description":"Start of the period during which the resource was observed running this SKU. A resource that switched SKUs (e.g. instance-type resize) will have multiple ResourceSKU rows with disjoint `[usage_start, usage_end]` windows."},"usage_end":{"type":"string","format":"date-time","description":"End of the period during which the resource was observed running this SKU. Within ~2 days of now generally indicates the resource is currently active with this SKU."},"tags":{"type":"object","description":"Merged provider + user tags (user tags take precedence). Empty when the resource has no tags. Use the `untagged` filter to find resources with no tags at all.","additionalProperties":{"type":"string"},"nullable":true},"total_cost":{"type":"number","description":"Trailing-30-day total spend on this resource — what the user actually paid, summing the on-demand, spot, and commitment-covered portions. Reflects actuals already incurred under existing commitments, NOT a projection. Zero for resources not active in the last month.","nullable":true},"ondemand_cost":{"type":"number","description":"Trailing-30-day on-demand-priced portion of `total_cost` — i.e. spend that wasn't covered by a commitment or run as spot. NOT the counterfactual 'what it would have cost at on-demand prices' (that's `if_all_ondemand_cost`).","nullable":true},"gross_savings":{"type":"number","description":"Trailing-30-day savings already realized on this resource vs the on-demand baseline (`if_all_ondemand_cost - total_cost`). Actuals from existing commitments — NOT a projection of what a candidate plan would save. Per-row clamped at zero, so summing this across resources never goes negative. Archera premium is NOT subtracted on this endpoint (premium isn't attributed per resource here); for portfolio-level net savings see /commitments/metrics.","nullable":true},"if_all_ondemand_cost":{"readOnly":true,"description":"Trailing-30-day on-demand counterfactual — what `total_cost` would be if every hour of usage ran at on-demand prices. Equals `total_cost + gross_savings`. Headline baseline for 'how much is this commitment-covered resource saving me'."},"coverage":{"type":"number","description":"Trailing-30-day spend-based fraction of this resource's usage covered by ALL existing commitments (0-1). At this single-SKU granularity, the usage-unit and spend ratios are equivalent. Actuals — the BEFORE picture relative to any candidate plan. When nested inside a commitment plan's covered-resources response, this is distinct from per-match `projected_coverage` (the AFTER picture for that plan).","nullable":true},"uptime":{"type":"number","description":"Trailing-30-day fraction of time the resource was running (0-1). Null for non-running SKU types (storage, data transfer, etc.). Useful for rightsizing flags — low uptime on a large instance is a candidate for downsizing or termination.","nullable":true},"parent_resource_id":{"type":"string","format":"uuid","description":"Parent Resource id (e.g. the spot fleet / autoscaling group / RDS cluster that owns this resource). Sparse — only populated when the cloud provider exposes a parent relationship. Use this to traverse resource hierarchies.","nullable":true},"description":{"type":"string","nullable":true},"location_type":{"type":"string","nullable":true},"physical_processor":{"type":"string","nullable":true},"clock_speed":{"type":"string","nullable":true},"processor_features":{"type":"string","nullable":true},"network_performance":{"type":"string","nullable":true},"storage":{"type":"string","nullable":true},"dedicated_ebs_throughput":{"type":"string","nullable":true},"io":{"type":"string","nullable":true},"tax_type":{"type":"string","nullable":true},"has_ondemand_terms":{"type":"boolean","nullable":true},"normalization_size_factor":{"type":"number","description":"AWS instance-size flexibility unit. Used internally to size convertible RIs across the family; not generally user-facing.","nullable":true},"publication_date":{"type":"string","format":"date-time","description":"When the catalog SKU version was published by the provider.","nullable":true},"end_date":{"type":"string","format":"date-time","description":"Date after which the catalog SKU is no longer available.","nullable":true},"attributes":{"description":"Raw provider-specific attribute blob from the catalog SKU — usually a JSON object, but can be any JSON value (string, list, etc.) since the underlying column is a Snowflake VARIANT. May overlap with the structured fields above; prefer the structured fields when they're populated.","nullable":true},"provider_tags":{"type":"object","description":"Tags assigned by the cloud provider, before user overrides are merged.","additionalProperties":{"type":"string"}},"user_tags":{"type":"object","description":"Tags applied via the Archera UI/API on top of the provider tags.","additionalProperties":{"type":"string"}},"covering_commitments":{"type":"array","description":"Per-commitment breakdown of CUDs covering this resource's usage over the requested period. Populated only when the request includes `expand=covering_commitments`; null otherwise to keep typical detail calls from paying the aggregation scan.","items":{"$ref":"#/components/schemas/CoveringCommitmentEntry"},"nullable":true}},"additionalProperties":false},"CoveringCommitmentEntry":{"type":"object","properties":{"commitment_id":{"type":"string","description":"Archera id of a commitment that covers this resource's usage."},"covered_usage":{"type":"number","description":"Sum of usage_amount_normalized this commitment covered on this resource over the period."},"share_pct":{"type":"number","description":"This commitment's share of the resource's total covered usage in the period, in [0, 1]. Across all rows this sums to 1."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Catalog (Beta)

Cloud SKU catalog — attribute filters, search, and per-SKU detail. Returns the public catalog plus the org's own custom-priced SKUs.

## List filterable catalog SKU attributes

> Returns the fields that can be used in the 'filter' parameter of the catalog SKU list endpoint, along with their types.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Catalog (Beta)","description":"Cloud SKU catalog — attribute filters, search, and per-SKU detail. Returns the public catalog plus the org's own custom-priced SKUs."}],"paths":{"/beta/v1/org/{org_id}/catalog/skus/attributes":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BaseAttribute"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"List filterable catalog SKU attributes","tags":["Catalog (Beta)"],"description":"Returns the fields that can be used in the 'filter' parameter of the catalog SKU list endpoint, along with their types."}}},"components":{"schemas":{"BaseAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean","integer","float","date","datetime","time","currency","percent","string","enum","uuid","tags"]}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get valid values for a filterable catalog SKU attribute

> Returns the distinct values for a given field, scoped to the same filters that would be applied on the list endpoint. Use this to narrow refinements (e.g. ask for valid instance\_type values for a given service+region before issuing a list call).

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Catalog (Beta)","description":"Cloud SKU catalog — attribute filters, search, and per-SKU detail. Returns the public catalog plus the org's own custom-priced SKUs."}],"paths":{"/beta/v1/org/{org_id}/catalog/skus/attributes/{field}":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"search","description":"Text search across SKU name, description, service, and the curated attribute fields (e.g. instance_type, region_code).","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields (`ondemand_usage_price`, `vcpu`, `memory`). Examples: {\"and\": [{\"field\": \"service\", \"op\": \"=\", \"value\": \"Amazon Elastic Compute Cloud - Compute\"}, {\"field\": \"instance_type\", \"op\": \"=\", \"value\": \"m5.large\"}]} — categorical; {\"field\": \"ondemand_usage_price\", \"op\": \"<\", \"value\": 0.10} — under $0.10/hr; {\"field\": \"vcpu\", \"op\": \">=\", \"value\": 16} — ≥16 vCPU. `memory` is in BYTES — divide by 2**30 for GiB / 1e9 for GB before comparing. Call /attributes for the filterable fields and /attributes/<field> for valid categorical values within the current scope.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by. Includes the numeric specs (`ondemand_usage_price`, `vcpu`, `memory`) for sorting by price or size.","schema":{"type":"string","default":"instance_type","enum":["instance_type","service","region_code","ondemand_usage_price","vcpu","memory"]},"required":false},{"in":"query","name":"desc","description":"Sort descending","schema":{"type":"boolean","default":false},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attribute"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"summary":"Get valid values for a filterable catalog SKU attribute","tags":["Catalog (Beta)"],"description":"Returns the distinct values for a given field, scoped to the same filters that would be applied on the list endpoint. Use this to narrow refinements (e.g. ask for valid instance_type values for a given service+region before issuing a list call)."}}},"components":{"schemas":{"Attribute":{"oneOf":[{"$ref":"#/components/schemas/BooleanAttribute"},{"$ref":"#/components/schemas/UUIDAttribute"},{"$ref":"#/components/schemas/StringAttribute"},{"$ref":"#/components/schemas/IntegerAttribute"},{"$ref":"#/components/schemas/FloatAttribute"},{"$ref":"#/components/schemas/CurrencyAttribute"},{"$ref":"#/components/schemas/PercentAttribute"},{"$ref":"#/components/schemas/DateTimeAttribute"},{"$ref":"#/components/schemas/DateAttribute"},{"$ref":"#/components/schemas/TimeAttribute"},{"$ref":"#/components/schemas/EnumAttribute"},{"$ref":"#/components/schemas/TagsAttribute"}],"discriminator":{"propertyName":"type","mapping":{"boolean":"#/components/schemas/BooleanAttribute","uuid":"#/components/schemas/UUIDAttribute","string":"#/components/schemas/StringAttribute","integer":"#/components/schemas/IntegerAttribute","float":"#/components/schemas/FloatAttribute","currency":"#/components/schemas/CurrencyAttribute","percent":"#/components/schemas/PercentAttribute","datetime":"#/components/schemas/DateTimeAttribute","date":"#/components/schemas/DateAttribute","time":"#/components/schemas/TimeAttribute","enum":"#/components/schemas/EnumAttribute","tags":"#/components/schemas/TagsAttribute"}}},"BooleanAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false},"UUIDAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["uuid"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"StringAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["string"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"IntegerAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["integer"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"FloatAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["float"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"CurrencyAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["currency"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"PercentAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["percent"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateTimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["datetime"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["date"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"TimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["time"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"EnumAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["enum"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"TagsAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["tags"],"readOnly":true},"tags":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["field","name","type"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## List catalog SKUs

> Returns SKUs from the public catalog plus the org's custom-priced SKUs, filtered to USD on-demand prices. To restrict to reservable SKUs, pass is\_reservable through the filter arg ({"field": "is\_reservable", "op": "=", "value": true}). \`X-Pagination\` is navigation-only: it always includes \`page\` and \`first\_page\`, and adds \`previous\_page\` and \`next\_page\` when available.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Catalog (Beta)","description":"Cloud SKU catalog — attribute filters, search, and per-SKU detail. Returns the public catalog plus the org's own custom-priced SKUs."}],"paths":{"/beta/v1/org/{org_id}/catalog/skus":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"search","description":"Text search across SKU name, description, service, and the curated attribute fields (e.g. instance_type, region_code).","schema":{"type":"string","default":null,"nullable":true},"required":false},{"in":"query","name":"filter","description":"JSON filter object — tree of {field, op, value} leaves combined with and / or / not. Supported ops: `=`, `!=`, `in` on any field; `>`, `>=`, `<`, `<=` on numeric fields (`ondemand_usage_price`, `vcpu`, `memory`). Examples: {\"and\": [{\"field\": \"service\", \"op\": \"=\", \"value\": \"Amazon Elastic Compute Cloud - Compute\"}, {\"field\": \"instance_type\", \"op\": \"=\", \"value\": \"m5.large\"}]} — categorical; {\"field\": \"ondemand_usage_price\", \"op\": \"<\", \"value\": 0.10} — under $0.10/hr; {\"field\": \"vcpu\", \"op\": \">=\", \"value\": 16} — ≥16 vCPU. `memory` is in BYTES — divide by 2**30 for GiB / 1e9 for GB before comparing. Call /attributes for the filterable fields and /attributes/<field> for valid categorical values within the current scope.","schema":{"type":"object","default":null,"additionalProperties":{},"nullable":true},"required":false},{"in":"query","name":"order_by","description":"Field to order results by. Includes the numeric specs (`ondemand_usage_price`, `vcpu`, `memory`) for sorting by price or size.","schema":{"type":"string","default":"instance_type","enum":["instance_type","service","region_code","ondemand_usage_price","vcpu","memory"]},"required":false},{"in":"query","name":"desc","description":"Sort descending","schema":{"type":"boolean","default":false},"required":false},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"page_size","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CatalogSKU"}}}},"headers":{"X-Pagination":{"$ref":"#/components/headers/PAGINATION"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Catalog (Beta)"],"summary":"List catalog SKUs","description":"Returns SKUs from the public catalog plus the org's custom-priced SKUs, filtered to USD on-demand prices. To restrict to reservable SKUs, pass is_reservable through the filter arg ({\"field\": \"is_reservable\", \"op\": \"=\", \"value\": true}). `X-Pagination` is navigation-only: it always includes `page` and `first_page`, and adds `previous_page` and `next_page` when available."}}},"components":{"schemas":{"CatalogSKU":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Catalog SKU id"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"provider_sku_id":{"type":"string","description":"Provider's own SKU identifier"},"name":{"type":"string","nullable":true},"family":{"type":"string","description":"Product family (e.g. 'Compute Instance')","nullable":true},"service":{"type":"string","description":"Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')","nullable":true},"provider_service":{"type":"string","description":"Provider service code (e.g. 'AmazonEC2')","nullable":true},"region_code":{"type":"string","description":"Region code (e.g. 'us-east-1')","nullable":true},"full_region_name":{"type":"string","description":"Full region name (e.g. 'US East (N. Virginia)')","nullable":true},"instance_type":{"type":"string","nullable":true},"instance_type_family":{"type":"string","nullable":true},"usage_type":{"type":"string","description":"Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items — useful for crossing between catalog and cost data.","nullable":true},"operation":{"type":"string","description":"Provider billing operation code (e.g. 'RunInstances:0002'). Lets the agent spot at-a-glance whether a SKU is the plain default operation or a more specific variant within a usage_type.","nullable":true},"operating_system":{"type":"string","nullable":true},"tenancy":{"type":"string","nullable":true},"database_engine":{"type":"string","nullable":true},"database_edition":{"type":"string","nullable":true},"cache_engine":{"type":"string","nullable":true},"is_multi_az":{"type":"boolean","nullable":true},"is_current_generation":{"type":"boolean","nullable":true},"license_model":{"type":"string","nullable":true},"pre_installed_sw":{"type":"string","nullable":true},"processor_architecture":{"type":"string","description":"CPU architecture (e.g. 'x86_64', 'arm64')","nullable":true},"vcpu":{"type":"number","nullable":true},"memory":{"type":"number","description":"Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.","nullable":true},"is_reservable":{"type":"boolean","description":"Whether this SKU has at least one reserved-term offering"},"is_public":{"type":"boolean","description":"True for public-catalog SKUs (the standard provider catalog). False when this row is the requesting org's own custom-priced SKU (tied to a specific integration; drill into `catalog_sku_details` for the integration_id)."},"ondemand_usage_unit":{"type":"string","nullable":true},"ondemand_usage_price":{"type":"number","description":"On-demand unit price in price_currency","nullable":true},"price_currency":{"type":"string","nullable":true}},"additionalProperties":false},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"headers":{"PAGINATION":{"description":"Pagination metadata","schema":{"$ref":"#/components/schemas/PaginationMetadata"}}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get catalog SKU detail

> Returns the full SKU record including hardware specs and (when available) the on-demand pricing terms with tiered price dimensions. Direct-id lookup doesn't apply the list endpoint's \`has\_ondemand\_terms\`/\`price\_currency=USD\` guards, so \`ondemand\_terms\` may be null and \`price\_currency\` may be non-USD for SKUs that wouldn't surface in the list. The SKU must be in the public catalog or owned by the requesting org.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Catalog (Beta)","description":"Cloud SKU catalog — attribute filters, search, and per-SKU detail. Returns the public catalog plus the org's own custom-priced SKUs."}],"paths":{"/beta/v1/org/{org_id}/catalog/skus/{sku_id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSKUDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Catalog (Beta)"],"summary":"Get catalog SKU detail","description":"Returns the full SKU record including hardware specs and (when available) the on-demand pricing terms with tiered price dimensions. Direct-id lookup doesn't apply the list endpoint's `has_ondemand_terms`/`price_currency=USD` guards, so `ondemand_terms` may be null and `price_currency` may be non-USD for SKUs that wouldn't surface in the list. The SKU must be in the public catalog or owned by the requesting org."}}},"components":{"schemas":{"CatalogSKUDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Catalog SKU id"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"provider_sku_id":{"type":"string","description":"Provider's own SKU identifier"},"name":{"type":"string","nullable":true},"family":{"type":"string","description":"Product family (e.g. 'Compute Instance')","nullable":true},"service":{"type":"string","description":"Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')","nullable":true},"provider_service":{"type":"string","description":"Provider service code (e.g. 'AmazonEC2')","nullable":true},"region_code":{"type":"string","description":"Region code (e.g. 'us-east-1')","nullable":true},"full_region_name":{"type":"string","description":"Full region name (e.g. 'US East (N. Virginia)')","nullable":true},"instance_type":{"type":"string","nullable":true},"instance_type_family":{"type":"string","nullable":true},"usage_type":{"type":"string","description":"Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items — useful for crossing between catalog and cost data.","nullable":true},"operation":{"type":"string","description":"Provider billing operation code (e.g. 'RunInstances:0002'). Lets the agent spot at-a-glance whether a SKU is the plain default operation or a more specific variant within a usage_type.","nullable":true},"operating_system":{"type":"string","nullable":true},"tenancy":{"type":"string","nullable":true},"database_engine":{"type":"string","nullable":true},"database_edition":{"type":"string","nullable":true},"cache_engine":{"type":"string","nullable":true},"is_multi_az":{"type":"boolean","nullable":true},"is_current_generation":{"type":"boolean","nullable":true},"license_model":{"type":"string","nullable":true},"pre_installed_sw":{"type":"string","nullable":true},"processor_architecture":{"type":"string","description":"CPU architecture (e.g. 'x86_64', 'arm64')","nullable":true},"vcpu":{"type":"number","nullable":true},"memory":{"type":"number","description":"Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.","nullable":true},"is_reservable":{"type":"boolean","description":"Whether this SKU has at least one reserved-term offering"},"is_public":{"type":"boolean","description":"True for public-catalog SKUs (the standard provider catalog). False when this row is the requesting org's own custom-priced SKU (tied to a specific integration; drill into `catalog_sku_details` for the integration_id)."},"ondemand_usage_unit":{"type":"string","nullable":true},"ondemand_usage_price":{"type":"number","description":"On-demand unit price in price_currency","nullable":true},"price_currency":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"location_type":{"type":"string","nullable":true},"availability_zone":{"type":"string","nullable":true},"physical_processor":{"type":"string","nullable":true},"clock_speed":{"type":"string","nullable":true},"processor_features":{"type":"string","nullable":true},"network_performance":{"type":"string","nullable":true},"storage":{"type":"string","nullable":true},"dedicated_ebs_throughput":{"type":"string","nullable":true},"io":{"type":"string","nullable":true},"tax_type":{"type":"string","nullable":true},"has_ondemand_terms":{"type":"boolean"},"normalization_size_factor":{"type":"number","description":"AWS instance-size flexibility unit. Used internally to size convertible RIs across the family; not generally user-facing.","nullable":true},"is_byol":{"type":"boolean","description":"Whether this SKU is a Bring-Your-Own-License variant. Derived from license_model."},"integration_id":{"type":"string","format":"uuid","description":"Integration this SKU's custom pricing is tied to. Null for public-catalog SKUs (the default scope of the list endpoint). Set when the SKU id resolves to a custom-priced SKU on the requesting org — direct-id detail lookups support both public and the org's own custom-priced SKUs.","nullable":true},"end_date":{"type":"string","format":"date-time","description":"Date after which this SKU is no longer available.","nullable":true},"publication_date":{"type":"string","format":"date-time","description":"When this SKU version was published by the provider.","nullable":true},"updated_at":{"type":"string","format":"date","description":"When this SKU was last refreshed in our catalog.","nullable":true},"attributes":{"type":"object","description":"Raw provider-specific attribute blob. May overlap with the structured fields above; prefer the structured fields when they're populated.","additionalProperties":{},"nullable":true},"ondemand_terms":{"anyOf":[{"type":"object","nullable":true},{"$ref":"#/components/schemas/SKUTerms"}]}},"additionalProperties":false},"SKUTerms":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"effective_date":{"type":"string","format":"date-time","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_unit":{"type":"string","nullable":true},"usage_unit_price":{"type":"number","nullable":true},"price_dimensions":{"type":"array","items":{"$ref":"#/components/schemas/PriceDimension"}}},"additionalProperties":false},"PriceDimension":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"description":{"type":"string","nullable":true},"usage_unit":{"type":"string","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_unit_price":{"type":"number","nullable":true},"begin_range":{"type":"number","description":"Tier lower bound (in usage units)","nullable":true},"end_range":{"type":"number","description":"Tier upper bound (in usage units); null means infinite","nullable":true}},"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Compare commitment offers for one or more hypothetical CatalogSKUs

> Loads 1-100 CatalogSKUs and their offer grids in bulk, then returns per-SKU candidates plus cross-SKU term/payment rollups. A one-item sku\_ids list is the single-SKU special case. Hypothetical and not tied to existing commitments — for swapping a line item's offer, use \`/commitment-plans/{plan\_id}/comparison\`. Missing, non-reservable, unpriced, or unmatched SKUs are returned in \`skipped\_skus\` with a reason and excluded from aggregate totals so valid SKUs still compare in the same request. Returns 4xx only when none of the requested SKUs pass access and input validation.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Catalog (Beta)","description":"Cloud SKU catalog — attribute filters, search, and per-SKU detail. Returns the public catalog plus the org's own custom-priced SKUs."}],"paths":{"/beta/v1/org/{org_id}/catalog/skus/offer-comparison":{"get":{"parameters":[{"in":"query","name":"sku_ids","description":"CatalogSKU ids to compare. Accepts 1-100 ids; a one-item list is the single-SKU special case. Every SKU uses the shared quantity.","schema":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}},"required":true,"explode":true,"style":"form"},{"in":"query","name":"quantity","description":"Number of SKU units to hypothetically commit to (≥1). Defaults to 1 for a simple pricing comparison. Pass an explicit quantity when the user wants absolute dollar figures (monthly savings, upfront cost) sized to a real purchase. For compute this is instance count; for non-compute SKUs the unit is the SKU's `ondemand_usage_unit`.","schema":{"type":"integer","default":1,"minimum":1},"required":false},{"in":"query","name":"contract_terms","description":"Optional list of contract terms to include (e.g. ['one_year_gris', 'three_year']). If omitted, includes every distinct term that appears across the requested SKUs' candidates after the payment-option filter.","schema":{"type":"array","default":null,"items":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"nullable":true},"required":false,"explode":true,"style":"form"},{"in":"query","name":"payment_options","description":"Payment options to include. Defaults to no_upfront only — matches the framing of the other beta comparison endpoints. Pass partial_upfront / all_upfront explicitly to surface those.","schema":{"type":"array","items":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":false,"explode":true,"style":"form"},{"in":"query","name":"only_most_flexible_commitment_type","description":"When true (default), `candidates[]` and `targets[]` are restricted to the most flexible commitment type available for the SKU's service. For EC2 SKUs that means Compute Savings Plans only — EC2 Reserved Instances and EC2 Instance Savings Plans are excluded because they bind to a single instance family + region, while Compute SPs cover any EC2 / Fargate / Lambda usage. For Azure Virtual Machines SKUs that means Azure Savings Plans only. Azure reservations are excluded because they bind more narrowly than Savings Plans. Same default-deemphasize spirit as `payment_options=['no_upfront']`. Pass false when the user explicitly asks about RIs/reservations, instance-family commitments, standard vs convertible, or 'all options.' For other SKUs this is a no-op today.","schema":{"type":"boolean","default":true},"required":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSKUOfferComparisonResponse"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found"},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Catalog (Beta)"],"summary":"Compare commitment offers for one or more hypothetical CatalogSKUs","description":"Loads 1-100 CatalogSKUs and their offer grids in bulk, then returns per-SKU candidates plus cross-SKU term/payment rollups. A one-item sku_ids list is the single-SKU special case. Hypothetical and not tied to existing commitments — for swapping a line item's offer, use `/commitment-plans/{plan_id}/comparison`. Missing, non-reservable, unpriced, or unmatched SKUs are returned in `skipped_skus` with a reason and excluded from aggregate totals so valid SKUs still compare in the same request. Returns 4xx only when none of the requested SKUs pass access and input validation."}}},"components":{"schemas":{"CatalogSKUOfferComparisonResponse":{"type":"object","properties":{"ondemand_baseline_monthly_cost":{"type":"number","description":"Combined average monthly on-demand cost across matched SKUs at each row's covered_quantity, normalized for time-based billing units."},"hypothetical_totals":{"type":"array","items":{"$ref":"#/components/schemas/CatalogSKUHypotheticalTotal"}},"data":{"type":"array","description":"Per-SKU comparison detail in request order.","items":{"$ref":"#/components/schemas/CatalogSKUOfferComparisonRow"}},"skipped_skus":{"type":"array","description":"Requested SKUs that were missing, inaccessible, non-reservable, unpriced, unmatched, or could not be priced, and were excluded from data and totals.","items":{"$ref":"#/components/schemas/SkippedCatalogSKU"}}},"required":["data","hypothetical_totals","ondemand_baseline_monthly_cost","skipped_skus"],"additionalProperties":false},"CatalogSKUHypotheticalTotal":{"type":"object","properties":{"contract_term":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"commitment_upfront_cost":{"type":"number"},"delta_vs_ondemand":{"$ref":"#/components/schemas/CatalogSKUTargetDelta"},"skus":{"type":"array","description":"Per-SKU resolution for this rollup. Surface fallback and no-alternative rows instead of implying every SKU matched the requested term.","items":{"$ref":"#/components/schemas/CatalogSKUResolution"}}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_ondemand","payment_option","skus"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CatalogSKUTargetDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Monthly net savings under this target's resolved candidate vs running on-demand. Equals `commitment_financials_monthly_rate.commitment_savings.net` when a candidate resolved; 0 when `actual_term_reason='no_alternative'` (no commitment, you stay on-demand)."},"monthly_commitment_cost":{"type":"number","description":"Monthly commitment cost under this target's resolved candidate. 0 when no alternative resolved."},"upfront_cost":{"type":"number","description":"One-time upfront dollars under this target's resolved candidate. 0 when no alternative resolved. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"CatalogSKUResolution":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid"},"actual_term":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"]}},"required":["actual_payment_option","actual_term","actual_term_reason","sku_id"],"additionalProperties":false},"CatalogSKUOfferComparisonRow":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid","description":"The CatalogSKU id compared."},"quantity":{"type":"integer","description":"Requested catalog quantity."},"covered_quantity":{"type":"number","description":"Catalog quantity covered after provider package-size and normalized-unit rounding. May exceed quantity when offers are sold in indivisible blocks."},"ondemand_baseline":{"description":"On-demand reference point. Compare against each candidate's `commitment_financials_monthly_rate.commitment_cost.total` to see the absolute savings, or read `discount_rate` for the relative figure.","allOf":[{"$ref":"#/components/schemas/CatalogSKUOndemandBaseline"}]},"candidates":{"type":"array","description":"All (offer, lease) pairs available for this SKU at the requested quantity, filtered to the requested contract_terms and payment_options. Ordered by descending discount_rate.","items":{"$ref":"#/components/schemas/CatalogSKUOfferComparisonEntry"}},"targets":{"type":"array","description":"One entry per requested (contract_term, payment_option) target — what the SKU resolves to under that hypothetical, with `actual_term_reason` explaining whether it was an exact match, a fallback to the closest shorter term, or no alternative. Mirrors the line-item endpoint's `hypothetical_totals` shape within this per-SKU response row. The headline 'should I do this' answer per target is `delta_vs_ondemand.monthly_net_savings`.","items":{"$ref":"#/components/schemas/CatalogSKUTarget"}}},"required":["candidates","covered_quantity","ondemand_baseline","quantity","sku_id","targets"],"additionalProperties":false},"CatalogSKUOndemandBaseline":{"type":"object","properties":{"monthly_cost":{"type":"number","description":"Average monthly on-demand cost for covered_quantity. Hourly rates are multiplied by 730; day, month, and year units are normalized to the same average-month basis."},"ondemand_usage_unit":{"type":"string","description":"Unit of measurement for on-demand usage (e.g. 'Hrs').","nullable":true},"ondemand_usage_price":{"type":"number","description":"Per-unit on-demand price in USD."}},"required":["monthly_cost","ondemand_usage_price"],"additionalProperties":false},"CatalogSKUOfferComparisonEntry":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Commitment offer id."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for a native (non-Archera) commitment.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Match the underlying offer.type to interpret."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. 'one_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). The real lock-in period, not the offer's raw duration.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Payment option (no_upfront / partial_upfront / all_upfront).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1)."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself; null if undefined.","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as line items / plans. `commitment_savings.net` is the headline savings vs running on-demand.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","discount_rate","lease_menu_item_id","offer","offer_id","payment_option","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CatalogSKUTarget":{"type":"object","properties":{"contract_term":{"description":"Requested contract term for this hypothetical.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Requested payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"actual_term":{"description":"The contract term that actually resolved. Equals `contract_term` when an exact match exists; otherwise the longest term shorter than the target with the same payment option. Null when no alternative exists for the requested (term, payment) pair.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the resolved candidate. Equals `payment_option` whenever a candidate resolved (resolution preserves payment option); null when no alternative.","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this target landed at `actual_term`. `exact_match` = the SKU offers exactly this (term, payment). `fallback_closest_shorter` = no exact match; resolved to the longest term shorter than target with the same payment option (GRI variant preferred when same duration). `no_alternative` = nothing qualifies; surfaced explicitly so the agent can flag to the user that this (term, payment) combination doesn't exist for the SKU."},"candidate":{"description":"The resolved (offer, lease) candidate, or null when `actual_term_reason='no_alternative'`. Same shape as entries in `candidates[]` — the agent can quote `discount_rate`, `breakeven_days`, etc. directly off this nested entry.","anyOf":[{"$ref":"#/components/schemas/CatalogSKUOfferComparisonEntry"},{"type":"object","nullable":true}]},"commitment_financials_monthly_rate":{"description":"Resolved candidate's 730-hour monthly-rate financials, lifted to the top level so the agent can read the same paths as on the line-item endpoint's `hypothetical_totals[i]`. All-zero when `actual_term_reason='no_alternative'`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Resolved candidate's one-time upfront cost. 0 when no alternative resolved. NOT a rate."},"delta_vs_ondemand":{"description":"Axis-by-axis difference vs the on-demand baseline. Analogous to `delta_vs_current` on the line-item endpoint, but the baseline is on-demand (zero commitment) so each field equals the resolved candidate's value directly.","allOf":[{"$ref":"#/components/schemas/CatalogSKUTargetDelta"}]}},"required":["actual_payment_option","actual_term","actual_term_reason","candidate","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_ondemand","payment_option"],"additionalProperties":false},"SkippedCatalogSKU":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid"},"reason":{"type":"string"}},"required":["reason","sku_id"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Organizations (Beta)

List and manage organizations the authenticated caller can access.

## List organizations the caller can access

> Returns every organization the authenticated user / API key can act in, ordered with the primary (default-fallback) org first. Use this to discover valid \`org\_id\` values to pass into other beta tools — required for users who belong to multiple orgs and want to scope a particular call to a non-primary org.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationMembership"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Organizations (Beta)"],"summary":"List organizations the caller can access","description":"Returns every organization the authenticated user / API key can act in, ordered with the primary (default-fallback) org first. Use this to discover valid `org_id` values to pass into other beta tools — required for users who belong to multiple orgs and want to scope a particular call to a non-primary org."}}},"components":{"schemas":{"OrganizationMembership":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID. Pass as `org_id` to other tools."},"name":{"type":"string","description":"Human-readable organization name."},"domain":{"type":"string","description":"Email domain associated with the org (e.g. 'acme.com'), or null if unset. For other org-management fields (postal address, deactivation flag, created_at), use `get_organization` on a specific `org_id`.","nullable":true},"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"],"description":"Caller's role in this org: 'user', 'admin', 'support', 'cloud_rep', or 'restricted_user'. Staff users are reported as 'admin' for every active org."},"kind":{"description":"How the caller has access: 'direct' (regular member), 'staff' (staff-level access to every active org), or 'partnership' (inherited via a channel partnership).","enum":["direct","staff","partnership"]},"is_primary":{"type":"boolean","description":"True for the org the caller's tokens default to when no `org_id` is passed. Matches the earliest-joined direct membership returned by `User.active_memberships`."},"denied_permissions":{"type":"array","description":"List of `Resource:action` strings the caller's role is denied (e.g. 'PurchasePlanV2:execute'). Anything not listed is permitted. Use to gate write/destructive recommendations.","items":{"type":"string"}}},"required":["denied_permissions","id","is_primary","kind","name","role"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Get an organization's management details

> Returns the org-management view of a single organization: name, domain, primary address, deactivation flag, and created\_at. For the cross-org list of orgs the caller can access (with role / kind / denied\_permissions), use \`GET /organizations\`.

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations/{org_id}":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Organizations (Beta)"],"summary":"Get an organization's management details","description":"Returns the org-management view of a single organization: name, domain, primary address, deactivation flag, and created_at. For the cross-org list of orgs the caller can access (with role / kind / denied_permissions), use `GET /organizations`."}}},"components":{"schemas":{"OrganizationDetail":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"description":"Organization ID."},"name":{"type":"string","description":"Organization name. Unique across the platform."},"domain":{"type":"string","description":"Email domain associated with the org (e.g. 'acme.com'). Used for domain-based onboarding flows.","nullable":true},"created_at":{"type":"string","format":"date-time","readOnly":true,"description":"When the org was created."},"primary_address":{"description":"The org's primary postal address (optional).","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"required":["name"],"additionalProperties":false},"Address":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true,"description":"Address identifier."},"line1":{"type":"string","description":"Street address, line 1."},"line2":{"type":"string","default":null,"description":"Street address, line 2 (optional).","nullable":true},"city":{"type":"string","description":"City."},"state":{"type":"string","description":"State / region / province."},"zip":{"type":"string","description":"Postal / ZIP code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB')."}},"required":["city","country","line1","state","zip"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Update an organization's management details

> Partial-update: every field is optional. Send only the fields you want to change. Sending \`primary\_address\` replaces the existing address in full; pass null to clear it. Deactivation is intentionally not exposed here — use \`POST /organizations/\<org\_id>/deactivate\`. Requires the caller to have admin role on the org (the \`Organization:write\` casbin permission).

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations/{org_id}":{"patch":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDetail"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganization"}}}},"tags":["Organizations (Beta)"],"summary":"Update an organization's management details","description":"Partial-update: every field is optional. Send only the fields you want to change. Sending `primary_address` replaces the existing address in full; pass null to clear it. Deactivation is intentionally not exposed here — use `POST /organizations/<org_id>/deactivate`. Requires the caller to have admin role on the org (the `Organization:write` casbin permission)."}}},"components":{"schemas":{"OrganizationDetail":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"description":"Organization ID."},"name":{"type":"string","description":"Organization name. Unique across the platform."},"domain":{"type":"string","description":"Email domain associated with the org (e.g. 'acme.com'). Used for domain-based onboarding flows.","nullable":true},"created_at":{"type":"string","format":"date-time","readOnly":true,"description":"When the org was created."},"primary_address":{"description":"The org's primary postal address (optional).","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"required":["name"],"additionalProperties":false},"Address":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true,"description":"Address identifier."},"line1":{"type":"string","description":"Street address, line 1."},"line2":{"type":"string","default":null,"description":"Street address, line 2 (optional).","nullable":true},"city":{"type":"string","description":"City."},"state":{"type":"string","description":"State / region / province."},"zip":{"type":"string","description":"Postal / ZIP code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB')."}},"required":["city","country","line1","state","zip"],"additionalProperties":false},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false},"UpdateOrganization":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"New organization name."},"domain":{"type":"string","minLength":1,"description":"New email domain, or null to clear.","nullable":true},"primary_address":{"description":"Replacement primary address. Send the full address object. Pass null to clear the existing address.","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"additionalProperties":false}},"responses":{"UNPROCESSABLE_CONTENT":{"description":"Unprocessable Content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```

## Deactivate an organization

> Soft-disables the organization: it stops appearing in \`list\_organizations\` results and members lose access. Intentionally a one-way door from this API surface — there is no corresponding reactivate endpoint, and once deactivated the org cannot be reached via these admin endpoints at all (the auth layer filters deactivated orgs). Reactivation requires reaching out to Archera support. Returns 204 with no body — there is no further state the caller can read post-deactivation. Requires the caller to have admin role on the org (the \`Organization:write\` casbin permission).

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Organizations (Beta)","description":"List and manage organizations the authenticated caller can access."}],"paths":{"/beta/v1/organizations/{org_id}/deactivate":{"post":{"responses":{"204":{"description":"No Content"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Organizations (Beta)"],"summary":"Deactivate an organization","description":"Soft-disables the organization: it stops appearing in `list_organizations` results and members lose access. Intentionally a one-way door from this API surface — there is no corresponding reactivate endpoint, and once deactivated the org cannot be reached via these admin endpoints at all (the auth layer filters deactivated orgs). Reactivation requires reaching out to Archera support. Returns 204 with no body — there is no further state the caller can read post-deactivation. Requires the caller to have admin role on the org (the `Organization:write` casbin permission)."}}},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


# Models

## The Error object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}}}}
```

## The PaginationMetadata object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"PaginationMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of items."},"total_pages":{"type":"integer","description":"Total number of pages."},"first_page":{"type":"integer","description":"First available page number."},"last_page":{"type":"integer","description":"Last available page number."},"page":{"type":"integer","description":"Current page number."},"previous_page":{"type":"integer","description":"Previous page number."},"next_page":{"type":"integer","description":"Next page number."}},"additionalProperties":false}}}}
```

## The ApiErrorResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]}}}}
```

## The PartnerArcheraPremiumsAndRebatesByChildOrgOutput object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"PartnerArcheraPremiumsAndRebatesByChildOrgOutput":{"type":"object","properties":{"org_id":{"type":"string","description":"Child organization identifier"},"org_name":{"type":"string","description":"Child organization name"},"archera_premiums":{"type":"number","description":"Archera premiums for this organization"},"rebates":{"type":"number","description":"Rebates for this organization"},"gross_savings":{"type":"number","description":"Gross savings for this organization"},"net_savings":{"type":"number","description":"Net savings for this organization"}},"additionalProperties":false}}}}
```

## The ArcheraPremiumsAndRebatesByAccountOutput object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ArcheraPremiumsAndRebatesByAccountOutput":{"type":"object","properties":{"account_id":{"type":"string","description":"Cloud account identifier"},"account_name":{"type":"string","description":"Human-readable account name"},"archera_premiums":{"type":"number","description":"Archera premiums allocated to this account"},"rebates":{"type":"number","description":"Rebates allocated to this account"},"gross_savings":{"type":"number","description":"Gross savings allocated to this account"},"net_savings":{"type":"number","description":"Net savings allocated to this account"}},"additionalProperties":false}}}}
```

## The ArcheraPremiumsAndRebatesDailyOutput object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ArcheraPremiumsAndRebatesDailyOutput":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Calendar date within the requested month"},"gross_savings":{"type":"number","description":"Gross savings allocated to this date"},"archera_premiums":{"type":"number","description":"Archera premiums allocated to this date"},"rebates":{"type":"number","description":"Rebates allocated to this date"},"net_savings":{"type":"number","description":"Net savings allocated to this date"}},"additionalProperties":false}}}}
```

## The ArcheraPremiumsAndRebatesByAccountDailyOutput object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ArcheraPremiumsAndRebatesByAccountDailyOutput":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Calendar date within the requested month"},"account_id":{"type":"string","description":"Cloud account identifier"},"account_name":{"type":"string","description":"Human-readable account name"},"gross_savings":{"type":"number","description":"Gross savings allocated to this account on this date"},"archera_premiums":{"type":"number","description":"Archera premiums allocated to this account on this date"},"rebates":{"type":"number","description":"Rebates allocated to this account on this date"},"net_savings":{"type":"number","description":"Net savings allocated to this account on this date"}},"additionalProperties":false}}}}
```

## The AllocationReportParamDescriptor object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"AllocationReportParamDescriptor":{"type":"object","properties":{"name":{"type":"string","description":"Query parameter name."},"type":{"type":"string","description":"JSON type: 'integer', 'number', 'string', or 'boolean'."},"required":{"type":"boolean","description":"Whether the parameter must be supplied."},"description":{"type":"string","description":"What the parameter controls."}},"additionalProperties":false}}}}
```

## The AllocationReportFieldDescriptor object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"AllocationReportFieldDescriptor":{"type":"object","properties":{"name":{"type":"string","description":"Output column name (snake_case in JSON)."},"type":{"type":"string","description":"JSON type of the column value."},"description":{"type":"string","description":"What the column represents."}},"additionalProperties":false}}}}
```

## The AllocationReportDescriptor object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"AllocationReportDescriptor":{"type":"object","properties":{"report_type":{"type":"string","description":"Identifier used as the path segment on the get endpoint (`/allocation-reports/<report_type>`)."},"name":{"type":"string","description":"Human-readable report title."},"description":{"type":"string","description":"What the report contains."},"category":{"type":"string","description":"Allocation tier. 'premiums_and_rebates' = Archera-side overlay only. 'commitment' = commitment cost redistributed from holding to usage accounts (typically with overlay alongside). 'cloud_bill' = full cloud bill including commitment + on-demand + Archera adjustments."},"row_grain":{"type":"string","description":"Time grain each row represents: 'monthly' (one row per calendar month, usually paired with another dim) or 'daily' (one row per calendar date)."},"update_cadence":{"type":"string","description":"When the report's underlying data changes. 'daily' = refreshes each day as new utilization lands; current-period previews are available and freeze after the period's invoice closes. 'on_period_close' = single snapshot when the invoice generates; calling for the current period returns empty until close. 'static' = never changes."},"params":{"type":"array","description":"Query parameters this report accepts.","items":{"$ref":"#/components/schemas/AllocationReportParamDescriptor"}},"output_fields":{"type":"array","description":"Columns each row of the report contains.","items":{"$ref":"#/components/schemas/AllocationReportFieldDescriptor"}}},"additionalProperties":false},"AllocationReportParamDescriptor":{"type":"object","properties":{"name":{"type":"string","description":"Query parameter name."},"type":{"type":"string","description":"JSON type: 'integer', 'number', 'string', or 'boolean'."},"required":{"type":"boolean","description":"Whether the parameter must be supplied."},"description":{"type":"string","description":"What the parameter controls."}},"additionalProperties":false},"AllocationReportFieldDescriptor":{"type":"object","properties":{"name":{"type":"string","description":"Output column name (snake_case in JSON)."},"type":{"type":"string","description":"JSON type of the column value."},"description":{"type":"string","description":"What the column represents."}},"additionalProperties":false}}}}
```

## The CloudProviderCostBreakdown object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false}}}}
```

## The CloudProviderCost object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false}}}}
```

## The CommitmentCostBreakdown object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false}}}}
```

## The CommitmentCost object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false}}}}
```

## The CommitmentSavings\_Exclude\_Rebate object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The CommitmentFinancialsNoRebate object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The ConfigurationContractSpec object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false}}}}
```

## The CommitmentPlanConfiguration object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false}}}}
```

## The CommitmentPlanList object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentPlanList":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]}},"required":["created_at","id","is_calculating","is_renewal","max_term","minimum_commitment","name","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false}}}}
```

## The CreateCommitmentPlanArgs object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CreateCommitmentPlanArgs":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"segment_id":{"type":"string","format":"uuid","default":null,"description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","nullable":true},"name":{"type":"string","description":"Human-readable plan name"},"configuration":{"description":"Inputs that drive plan generation","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]}},"required":["configuration","name","provider"],"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false}}}}
```

## The RenewalCommitmentPlanConfiguration object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"RenewalCommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating renewal line items. Each spec is a (commitment_type, contract_term, payment_option) triple — the recommender picks the best mix matching these specs against the expiring commitments' usage.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"renewal_commitment_ids":{"type":"array","minItems":1,"description":"Expiring commitment ids to renew. Required and non-empty. All ids must belong to the caller's org and the supplied provider, and each must have a non-null end_date (used to derive the usage-window for the renewal recommendation).","items":{"type":"string","format":"uuid"}}},"required":["contract_specs","renewal_commitment_ids"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false}}}}
```

## The CreateRenewalCommitmentPlanArgs object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CreateRenewalCommitmentPlanArgs":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Human-readable plan name"},"configuration":{"description":"Inputs that drive plan generation, including the source `renewal_commitment_ids`. Renewal config omits `lookback_days` (derived from source commitments' end dates) and `resource_ids` (replaced by `renewal_commitment_ids` inside this same object).","allOf":[{"$ref":"#/components/schemas/RenewalCommitmentPlanConfiguration"}]}},"required":["configuration","name","provider"],"additionalProperties":false},"RenewalCommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating renewal line items. Each spec is a (commitment_type, contract_term, payment_option) triple — the recommender picks the best mix matching these specs against the expiring commitments' usage.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"renewal_commitment_ids":{"type":"array","minItems":1,"description":"Expiring commitment ids to renew. Required and non-empty. All ids must belong to the caller's org and the supplied provider, and each must have a non-null end_date (used to derive the usage-window for the renewal recommendation).","items":{"type":"string","format":"uuid"}}},"required":["contract_specs","renewal_commitment_ids"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false}}}}
```

## The CommitmentPlan object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"current_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan."}},"required":["created_at","current_coverage","id","is_calculating","is_renewal","max_term","minimum_commitment","name","projected_coverage","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false}}}}
```

## The CoveredService object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CoveredService":{"type":"object","properties":{"service_name":{"type":"string","description":"Cloud service name (e.g. 'Amazon EC2', 'Amazon RDS')"},"num_commitments":{"type":"integer","description":"Number of individual commitments covering this service"},"current_coverage":{"type":"number","description":"Spend-based commitment coverage of this service's reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"Spend-based commitment coverage of this service's reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan."},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this service. cloud_provider_cost is `{total}` only (no recurring/amortized split at per-service level). commitment_savings has no rebate field on plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["current_coverage","num_commitments","projected_coverage","service_name"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The CommitmentPlanDetail object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentPlanDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"current_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan."},"covered_services":{"type":"array","description":"List of cloud services covered by this plan, with per-service savings and commitment breakdowns","items":{"$ref":"#/components/schemas/CoveredService"}}},"required":["created_at","current_coverage","id","is_calculating","is_renewal","max_term","minimum_commitment","name","projected_coverage","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"CoveredService":{"type":"object","properties":{"service_name":{"type":"string","description":"Cloud service name (e.g. 'Amazon EC2', 'Amazon RDS')"},"num_commitments":{"type":"integer","description":"Number of individual commitments covering this service"},"current_coverage":{"type":"number","description":"Spend-based commitment coverage of this service's reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"Spend-based commitment coverage of this service's reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan."},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this service. cloud_provider_cost is `{total}` only (no recurring/amortized split at per-service level). commitment_savings has no rebate field on plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["current_coverage","num_commitments","projected_coverage","service_name"],"additionalProperties":false}}}}
```

## The UpdateCommitmentPlanArgs object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"UpdateCommitmentPlanArgs":{"type":"object","properties":{"name":{"type":"string","description":"New plan name"},"configuration":{"description":"New plan configuration. Replacing this triggers a full regeneration of the plan's line items and financials. The plan's scope axis lives here too — `resource_ids` for infrastructure scope, `renewal_commitment_ids` for renewal scope (mutually exclusive). Sending the wrong scope field for the plan type is rejected; convert plan types by deleting and re-creating.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false}}}}
```

## The LineItemUpdateEntry object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"LineItemUpdateEntry":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"ID of the line item to update."},"is_selected":{"type":"boolean","description":"Include this line item in the plan's top-level financials and apply it when the plan is purchased."},"account_id":{"type":"string","description":"Cloud account ID this commitment is scoped to.","nullable":true},"offer_id":{"type":"string","format":"uuid","description":"Swap this line item's offer. Pair with `lease_menu_item_id` and `selected_amount` from the same comparison entry."},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to the chosen offer. Must come from the same comparison entry as `offer_id`. NULL VS OMITTED MATTERS: explicitly passing `null` clears the existing lease (converting a leased Archera-guaranteed commitment into a native one); omitting the field leaves the existing lease in place. To switch a leased GRI line item to a native offer, you MUST pass `null` here — otherwise the old lease stays attached and the line item's effective `contract_term` (derived from the lease's lockin hours) won't change.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount for the offer — unit count for RIs / unit-based CUDs, dollar-basis for Savings Plans / spend-based CUDs."}},"required":["line_item_id"],"additionalProperties":false}}}}
```

## The CopyCommitmentPlanArgs object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CopyCommitmentPlanArgs":{"type":"object","properties":{"target_contract_term":{"default":null,"description":"Server-side resolution mode. Set to a target contract term and the server resolves the per-line-item update set using the same fallback rule the comparison endpoint projects: exact match on (term, payment) where available, else closest shorter term with the same payment option (GRI preferred within tier). Mutually exclusive with explicit per-line-item updates — pass one OR the other, not both. Preferred over enumerating updates manually because the server can't silently omit entries from a list it builds itself.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"target_payment_option":{"default":"no_upfront","description":"Target payment option for resolution mode. Defaults to no_upfront — most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Ignored when `target_contract_term` is null.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"target_line_item_ids":{"type":"array","default":null,"description":"Optional subset of line items to update under resolution mode. If omitted, applies to all selected line items in the plan. Ignored when `target_contract_term` is null.","items":{"type":"string","format":"uuid"},"nullable":true},"name":{"type":"string","default":null,"description":"Name for the copied plan. If omitted, defaults to '<source plan name> <today's date>'.","nullable":true},"line_item_updates":{"type":"array","default":null,"description":"Optional list of line-item edits to apply during the copy. Each entry has the same shape as `update_commitment_plan_line_items`'s `updates` (line_item_id + optional is_selected / account_id / offer-swap triple). Entries reference the SOURCE plan's line_item_ids; the server translates them to the copy's new IDs internally and applies them atomically. If any edit fails, the entire copy + updates rolls back. Use this for the canonical 'copy to edit' workflow — saves the round trip and ID-translation logic that would otherwise live on the client. Mutually exclusive with `target_contract_term` (resolution mode).","items":{"$ref":"#/components/schemas/LineItemUpdateEntry"},"nullable":true}},"additionalProperties":false},"LineItemUpdateEntry":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"ID of the line item to update."},"is_selected":{"type":"boolean","description":"Include this line item in the plan's top-level financials and apply it when the plan is purchased."},"account_id":{"type":"string","description":"Cloud account ID this commitment is scoped to.","nullable":true},"offer_id":{"type":"string","format":"uuid","description":"Swap this line item's offer. Pair with `lease_menu_item_id` and `selected_amount` from the same comparison entry."},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to the chosen offer. Must come from the same comparison entry as `offer_id`. NULL VS OMITTED MATTERS: explicitly passing `null` clears the existing lease (converting a leased Archera-guaranteed commitment into a native one); omitting the field leaves the existing lease in place. To switch a leased GRI line item to a native offer, you MUST pass `null` here — otherwise the old lease stays attached and the line item's effective `contract_term` (derived from the lease's lockin hours) won't change.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount for the offer — unit count for RIs / unit-based CUDs, dollar-basis for Savings Plans / spend-based CUDs."}},"required":["line_item_id"],"additionalProperties":false}}}}
```

## The HypotheticalLineItem object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"HypotheticalLineItem":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"actual_term":{"description":"The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."}},"required":["actual_payment_option","actual_term","actual_term_reason","line_item_id"],"additionalProperties":false}}}}
```

## The PlanLineItemUpdateResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"PlanLineItemUpdateResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique plan identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Plan name (e.g. 'Recommended', 'Balanced', 'High Savings')"},"description":{"type":"string","description":"Human-readable summary of the plan","nullable":true},"is_renewal":{"type":"boolean","description":"True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments)."},"status":{"description":"Plan status (e.g. 'draft', 'in_progress', 'completed')","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"is_calculating":{"type":"boolean","description":"True if the plan is still being computed"},"created_at":{"type":"string","format":"date-time","description":"When the plan was generated"},"usage_start_date":{"type":"string","format":"date-time","description":"Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal_commitment_ids).","nullable":true},"usage_end_date":{"type":"string","format":"date-time","description":"End of the usage window the plan was computed from. Null on renewal plans (see usage_start_date).","nullable":true},"max_term":{"type":"string","description":"Maximum commitment term (e.g. '30_DAY', '1_YEAR', '3_YEAR')","nullable":true},"minimum_commitment":{"type":"number","description":"Minimum total spend being committed to"},"breakeven_days":{"readOnly":true,"description":"Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand."},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero."},"commitment_financials_monthly_rate":{"description":"Projected plan economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field — plans are proposals, no rebates accumulated.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"configuration":{"description":"The inputs that drove plan generation — the max_upfront_cost cap and the list of contract specs considered. Round-trips: a GET response can be round-tripped to PUT to re-run generation after editing.","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"resolution":{"type":"array","description":"Per-line-item resolution outcome when `target_contract_term` was passed. One entry per line item that was IN SCOPE for the request (covers `no_alternative` items too — those are not in the applied updates but are surfaced here so callers can see what the server couldn't satisfy). `actual_term_reason` is one of: `exact_match` (landed at target), `fallback_closest_shorter` (used the longest available term ≤ target with same payment option), `no_alternative` (no candidate satisfied — line item left unchanged). Absent / null on explicit-mode calls.","items":{"$ref":"#/components/schemas/HypotheticalLineItem"},"nullable":true}},"required":["created_at","id","is_calculating","is_renewal","max_term","minimum_commitment","name","provider","status"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"HypotheticalLineItem":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"actual_term":{"description":"The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."}},"required":["actual_payment_option","actual_term","actual_term_reason","line_item_id"],"additionalProperties":false}}}}
```

## The ContractSpec object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier"},"properties":{"type":"object","default":{},"description":"Additional contract properties","additionalProperties":{}},"term":{"description":"Contract term","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Payment option","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true}},"additionalProperties":false}}}}
```

## The CommitmentOffer object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false}}}}
```

## The CommitmentLineItem object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentLineItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Line item identifier"},"is_selected":{"type":"boolean","description":"Whether this line item is included in the plan. If false, this line item is excluded and its costs/savings are NOT reflected in the plan's top-level metrics."},"account_id":{"type":"string","description":"Cloud account ID this commitment applies to","nullable":true},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"contract_spec":{"description":"Detailed contract specifications including commitment type and properties","allOf":[{"$ref":"#/components/schemas/ContractSpec"}]},"offer":{"description":"Commitment offer details including type, region, and instance info","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1)"},"breakeven_days":{"readOnly":true,"description":"Days until this line item pays for itself"},"selected_amount":{"readOnly":true,"description":"Selected commitment amount — either a quantity (for RIs) or a dollar commitment (for Savings Plans), whichever is applicable"},"recommended_amount":{"readOnly":true,"description":"Recommended commitment amount — either a quantity (for RIs) or a dollar commitment (for Savings Plans), whichever is applicable"},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars required at signing for this specific line item. NOT a rate — do not sum with monthly-rate fields. Summing the commitment_upfront_cost of all selected line items equals the parent plan's commitment_upfront_cost."},"commitment_financials_monthly_rate":{"description":"Projected line item economics as 730-hour monthly rates. cloud_provider_cost includes full purchase-term detail (recurring, amortized_upfront). commitment_savings has no rebate field on plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"covered_services":{"type":"array","description":"Cloud service identifiers (e.g. 'AmazonEC2', 'AmazonRDS') that this line item's commitment is expected to cover. Reflects the underlying resources the recommender matched to this commitment, not the offer's raw eligibility.","items":{"type":"string"}},"renewal_commitment_id":{"type":"string","format":"uuid","description":"ID of the expiring commitment this line item is renewing. Populated only on renewal plans (`plan_type=renewal`); null on purchase / infrastructure plans. Use the `renewal_commitment_ids` query param on this endpoint to filter to the line items proposed as replacements for specific expiring commitments.","nullable":true}},"required":["id","is_selected"],"additionalProperties":false},"ContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier"},"properties":{"type":"object","default":{},"description":"Additional contract properties","additionalProperties":{}},"term":{"description":"Contract term","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Payment option","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true}},"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The UpdateLineItemsArgs object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"UpdateLineItemsArgs":{"type":"object","properties":{"target_contract_term":{"default":null,"description":"Server-side resolution mode. Set to a target contract term and the server resolves the per-line-item update set using the same fallback rule the comparison endpoint projects: exact match on (term, payment) where available, else closest shorter term with the same payment option (GRI preferred within tier). Mutually exclusive with explicit per-line-item updates — pass one OR the other, not both. Preferred over enumerating updates manually because the server can't silently omit entries from a list it builds itself.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"target_payment_option":{"default":"no_upfront","description":"Target payment option for resolution mode. Defaults to no_upfront — most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Ignored when `target_contract_term` is null.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"target_line_item_ids":{"type":"array","default":null,"description":"Optional subset of line items to update under resolution mode. If omitted, applies to all selected line items in the plan. Ignored when `target_contract_term` is null.","items":{"type":"string","format":"uuid"},"nullable":true},"updates":{"type":"array","default":null,"minItems":1,"description":"List of per-line-item updates to apply atomically. Required unless `target_contract_term` is set (resolution mode). Each entry's `line_item_id` must be on the parent plan.","items":{"$ref":"#/components/schemas/LineItemUpdateEntry"},"nullable":true}},"additionalProperties":false},"LineItemUpdateEntry":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"ID of the line item to update."},"is_selected":{"type":"boolean","description":"Include this line item in the plan's top-level financials and apply it when the plan is purchased."},"account_id":{"type":"string","description":"Cloud account ID this commitment is scoped to.","nullable":true},"offer_id":{"type":"string","format":"uuid","description":"Swap this line item's offer. Pair with `lease_menu_item_id` and `selected_amount` from the same comparison entry."},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to the chosen offer. Must come from the same comparison entry as `offer_id`. NULL VS OMITTED MATTERS: explicitly passing `null` clears the existing lease (converting a leased Archera-guaranteed commitment into a native one); omitting the field leaves the existing lease in place. To switch a leased GRI line item to a native offer, you MUST pass `null` here — otherwise the old lease stays attached and the line item's effective `contract_term` (derived from the lease's lockin hours) won't change.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount for the offer — unit count for RIs / unit-based CUDs, dollar-basis for Savings Plans / spend-based CUDs."}},"required":["line_item_id"],"additionalProperties":false}}}}
```

## The Commitment object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false}}}}
```

## The LineItemOfferComparisonTotals object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"LineItemOfferComparisonTotals":{"type":"object","properties":{"commitment_financials_monthly_rate":{"description":"730-hour monthly rate financials summed across the line items in scope. Same shape as on plans / line items.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars at signing across the line items in scope. NOT a rate — do not sum with monthly-rate fields."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The HypotheticalDelta object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"HypotheticalDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the plan does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The HypotheticalTotal object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"HypotheticalTotal":{"type":"object","properties":{"contract_term":{"description":"Target contract term for this hypothetical.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Target payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"description":"Rolled-up monthly-rate financials assuming each line item adopts its candidate per the fallback rule. Same shape as on plans / line items.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars across the line items under this hypothetical. NOT a rate."},"delta_vs_current":{"description":"Axis-by-axis difference vs current_totals. The headline 'should I do this' answer is delta_vs_current.monthly_net_savings.","allOf":[{"$ref":"#/components/schemas/HypotheticalDelta"}]},"line_items":{"type":"array","description":"Per-line-item resolution for this hypothetical. Use to call out fallbacks ('14 of 20 line items would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current').","items":{"$ref":"#/components/schemas/HypotheticalLineItem"}}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","line_items","payment_option"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"HypotheticalDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the plan does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"HypotheticalLineItem":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"actual_term":{"description":"The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."}},"required":["actual_payment_option","actual_term","actual_term_reason","line_item_id"],"additionalProperties":false}}}}
```

## The OfferComparisonDelta object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":"number","description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven.","nullable":true}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The OfferComparisonEntry object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"OfferComparisonEntry":{"type":"object","properties":{"is_current":{"type":"boolean","description":"True if this entry matches the line item's current offer + lease. Exactly one entry per response has this set; its `delta_vs_current` values are all zero."},"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost).","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","allOf":[{"$ref":"#/components/schemas/OfferComparisonDelta"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","is_current","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":"number","description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven.","nullable":true}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The LineItemOfferComparisonRow object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"LineItemOfferComparisonRow":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"current":{"description":"The line item's current offer + lease, in the same shape as OfferComparisonEntrySchema. Its delta_vs_current is all zeros.","allOf":[{"$ref":"#/components/schemas/OfferComparisonEntry"}]},"candidates":{"type":"array","description":"Alternative (offer, lease) pairs for this line item, filtered to the requested contract_terms and payment_options. Each entry carries its own contract_term and payment_option (on offer); fields offer_id, lease_menu_item_id, and selected_amount can be copied verbatim into POST /commitment-plans/{plan_id}/line-items/update (in the `updates` list) to swap the line item to that candidate.","items":{"$ref":"#/components/schemas/OfferComparisonEntry"}}},"required":["candidates","current","line_item_id"],"additionalProperties":false},"OfferComparisonEntry":{"type":"object","properties":{"is_current":{"type":"boolean","description":"True if this entry matches the line item's current offer + lease. Exactly one entry per response has this set; its `delta_vs_current` values are all zero."},"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost).","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","allOf":[{"$ref":"#/components/schemas/OfferComparisonDelta"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","is_current","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":"number","description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven.","nullable":true}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The LineItemOfferComparisonResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"LineItemOfferComparisonResponse":{"type":"object","properties":{"current_totals":{"description":"Plan-wide totals for the line items currently in scope (defaults to all selected, narrowed by line_item_ids if provided). Use this as the baseline when interpreting hypothetical deltas.","allOf":[{"$ref":"#/components/schemas/LineItemOfferComparisonTotals"}]},"hypothetical_totals":{"type":"array","description":"One entry per (contract_term, payment_option) combination requested (or per distinct term present in candidates if contract_terms was omitted). Each entry's totals + delta_vs_current answer 'what's the plan-wide impact of this term?' in one place — no client-side summing across line items required.","items":{"$ref":"#/components/schemas/HypotheticalTotal"}},"data":{"type":"array","description":"Per-line-item detail. Use when the user wants to drill into 'why does RDS not have a 3-year candidate' or to assemble an update payload.","items":{"$ref":"#/components/schemas/LineItemOfferComparisonRow"}}},"required":["current_totals","data","hypothetical_totals"],"additionalProperties":false},"LineItemOfferComparisonTotals":{"type":"object","properties":{"commitment_financials_monthly_rate":{"description":"730-hour monthly rate financials summed across the line items in scope. Same shape as on plans / line items.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars at signing across the line items in scope. NOT a rate — do not sum with monthly-rate fields."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"HypotheticalTotal":{"type":"object","properties":{"contract_term":{"description":"Target contract term for this hypothetical.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Target payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"description":"Rolled-up monthly-rate financials assuming each line item adopts its candidate per the fallback rule. Same shape as on plans / line items.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars across the line items under this hypothetical. NOT a rate."},"delta_vs_current":{"description":"Axis-by-axis difference vs current_totals. The headline 'should I do this' answer is delta_vs_current.monthly_net_savings.","allOf":[{"$ref":"#/components/schemas/HypotheticalDelta"}]},"line_items":{"type":"array","description":"Per-line-item resolution for this hypothetical. Use to call out fallbacks ('14 of 20 line items would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current').","items":{"$ref":"#/components/schemas/HypotheticalLineItem"}}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","line_items","payment_option"],"additionalProperties":false},"HypotheticalDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the plan does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"HypotheticalLineItem":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"actual_term":{"description":"The contract term this line item actually contributes to the rollup at. Equals the target term when an exact match exists; otherwise the longest available term <= target with the same payment option, or the line item's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this line item contributes. Equals the target payment option except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this line item landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."}},"required":["actual_payment_option","actual_term","actual_term_reason","line_item_id"],"additionalProperties":false},"LineItemOfferComparisonRow":{"type":"object","properties":{"line_item_id":{"type":"string","format":"uuid","description":"Line item ID."},"current":{"description":"The line item's current offer + lease, in the same shape as OfferComparisonEntrySchema. Its delta_vs_current is all zeros.","allOf":[{"$ref":"#/components/schemas/OfferComparisonEntry"}]},"candidates":{"type":"array","description":"Alternative (offer, lease) pairs for this line item, filtered to the requested contract_terms and payment_options. Each entry carries its own contract_term and payment_option (on offer); fields offer_id, lease_menu_item_id, and selected_amount can be copied verbatim into POST /commitment-plans/{plan_id}/line-items/update (in the `updates` list) to swap the line item to that candidate.","items":{"$ref":"#/components/schemas/OfferComparisonEntry"}}},"required":["candidates","current","line_item_id"],"additionalProperties":false},"OfferComparisonEntry":{"type":"object","properties":{"is_current":{"type":"boolean","description":"True if this entry matches the line item's current offer + lease. Exactly one entry per response has this set; its `delta_vs_current` values are all zero."},"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost).","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","allOf":[{"$ref":"#/components/schemas/OfferComparisonDelta"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","is_current","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":"number","description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven.","nullable":true}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The BaseAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"BaseAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean","integer","float","date","datetime","time","currency","percent","string","enum","uuid","tags"]}},"required":["field","name","type"],"additionalProperties":false}}}}
```

## The Filter object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false}}}}
```

## The BooleanAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"BooleanAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false}}}}
```

## The UUIDAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"UUIDAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["uuid"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false}}}}
```

## The StringAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"StringAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["string"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false}}}}
```

## The IntegerAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"IntegerAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["integer"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false}}}}
```

## The FloatAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"FloatAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["float"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false}}}}
```

## The CurrencyAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CurrencyAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["currency"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false}}}}
```

## The PercentAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"PercentAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["percent"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false}}}}
```

## The DateTimeAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DateTimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["datetime"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false}}}}
```

## The DateAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DateAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["date"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false}}}}
```

## The TimeAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"TimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["time"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false}}}}
```

## The EnumAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"EnumAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["enum"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false}}}}
```

## The TagsAttribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"TagsAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["tags"],"readOnly":true},"tags":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["field","name","type"],"additionalProperties":false}}}}
```

## The Attribute object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"Attribute":{"oneOf":[{"$ref":"#/components/schemas/BooleanAttribute"},{"$ref":"#/components/schemas/UUIDAttribute"},{"$ref":"#/components/schemas/StringAttribute"},{"$ref":"#/components/schemas/IntegerAttribute"},{"$ref":"#/components/schemas/FloatAttribute"},{"$ref":"#/components/schemas/CurrencyAttribute"},{"$ref":"#/components/schemas/PercentAttribute"},{"$ref":"#/components/schemas/DateTimeAttribute"},{"$ref":"#/components/schemas/DateAttribute"},{"$ref":"#/components/schemas/TimeAttribute"},{"$ref":"#/components/schemas/EnumAttribute"},{"$ref":"#/components/schemas/TagsAttribute"}],"discriminator":{"propertyName":"type","mapping":{"boolean":"#/components/schemas/BooleanAttribute","uuid":"#/components/schemas/UUIDAttribute","string":"#/components/schemas/StringAttribute","integer":"#/components/schemas/IntegerAttribute","float":"#/components/schemas/FloatAttribute","currency":"#/components/schemas/CurrencyAttribute","percent":"#/components/schemas/PercentAttribute","datetime":"#/components/schemas/DateTimeAttribute","date":"#/components/schemas/DateAttribute","time":"#/components/schemas/TimeAttribute","enum":"#/components/schemas/EnumAttribute","tags":"#/components/schemas/TagsAttribute"}}},"BooleanAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["boolean"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"Filter":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"},"op":{"type":"string","enum":["=","!=",">",">=","<","<=","in","has","contains"]}},"required":["field","op","value"],"additionalProperties":false},"UUIDAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["uuid"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"StringAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["string"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"IntegerAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["integer"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"FloatAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["float"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"CurrencyAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["currency"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"PercentAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["percent"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateTimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["datetime"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"DateAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["date"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"TimeAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["time"],"readOnly":true}},"required":["field","name","type"],"additionalProperties":false},"EnumAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["enum"],"readOnly":true},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Filter"}}},"required":["field","name","type"],"additionalProperties":false},"TagsAttribute":{"type":"object","properties":{"name":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["tags"],"readOnly":true},"tags":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["field","name","type"],"additionalProperties":false}}}}
```

## The ResourceMatchSummary object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ResourceMatchSummary":{"type":"object","properties":{"service":{"type":"string","description":"Cloud service name (e.g. 'AmazonEC2', 'AmazonRDS')","nullable":true},"account_id":{"type":"string","description":"Cloud account ID","nullable":true},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"resource_type":{"type":"string","description":"Resource type within this group — instance family for compute (e.g. 'm5'), usage type for other services (e.g. 'Fargate-GB-Hours', 'Lambda-GB-Second'), or SKU name as fallback","nullable":true},"resource_count":{"type":"integer","description":"Number of resources in this group"},"projected_coverage":{"type":"number","description":"Spend-based projected coverage across resources in this group (0-1), weighted by each resource's on-demand-equivalent cost. Distinct from `resource.coverage` (trailing-30-day actual spend-based coverage from existing commitments). For per-resource projected coverage, use the paginated /covered-resources endpoint."},"commitment_financials_monthly_rate":{"description":"Plan economics scoped to this resource group, as 730-hour monthly rates. cloud_provider_cost has `{total}` only — per-group aggregates don't have the recurring/amortized_upfront split. commitment_savings has no rebate field on plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The ResourceSKU object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ResourceSKU":{"type":"object","properties":{"id":{"type":"string","description":"Composite ResourceSKU id — `<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`. Pass directly to `/resources/skus/<id>` for detail; do not parse it client-side."},"resource_id":{"type":"string","format":"uuid","description":"Underlying Resource id. Stable across SKU/time variants of the same resource — multiple ResourceSKU rows can share a `resource_id` when the same resource ran with different SKUs over its lifetime."},"catalog_sku_id":{"type":"string","format":"uuid","description":"Join key into `/catalog/skus/<id>` for the public SKU record."},"catalog_sku_org_id":{"type":"string","description":"Org id that owns the catalog SKU — public-catalog SKUs use the public org id; custom-priced SKUs use the customer's org id."},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"provider_resource_id":{"type":"string","description":"Provider's id for the resource (AWS ARN, Azure resource ID, GCP resource name). This is the canonical identifier the user sees in the cloud console."},"provider_sku_id":{"type":"string","description":"Provider's own SKU identifier","nullable":true},"name":{"type":"string","description":"Resource name (Resource.name) — the user-applied label, e.g. 'prod-db-1'. Distinct from `sku_name`, which is the catalog SKU's display name.","nullable":true},"sku_name":{"type":"string","description":"Catalog SKU display name (e.g. 'Amazon EC2 Instance', 'Amazon Aurora PostgreSQL Cluster'). Useful as a fallback label when `instance_type_family` and `usage_type` are both null. Distinct from `name` (the resource's user-applied label).","nullable":true},"integration_id":{"type":"string","description":"Integration this resource belongs to"},"billing_account_id":{"type":"string","description":"Provider billing/management account id","nullable":true},"sub_account_id":{"type":"string","description":"Provider account id that owns/created the resource","nullable":true},"resource_group":{"type":"string","nullable":true},"is_spot":{"type":"boolean","nullable":true},"availability_zone":{"type":"string","nullable":true},"service":{"type":"string","description":"Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')","nullable":true},"provider_service":{"type":"string","description":"Provider service code (e.g. 'AmazonEC2')","nullable":true},"family":{"type":"string","description":"Product family (e.g. 'Compute Instance')","nullable":true},"region_code":{"type":"string","description":"Region code (e.g. 'us-east-1')","nullable":true},"full_region_name":{"type":"string","description":"Full region name (e.g. 'US East (N. Virginia)')","nullable":true},"instance_type":{"type":"string","nullable":true},"instance_type_family":{"type":"string","nullable":true},"usage_type":{"type":"string","description":"Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items.","nullable":true},"operation":{"type":"string","description":"Provider billing operation code (e.g. 'RunInstances:0002')","nullable":true},"operating_system":{"type":"string","nullable":true},"tenancy":{"type":"string","nullable":true},"database_engine":{"type":"string","nullable":true},"database_edition":{"type":"string","nullable":true},"cache_engine":{"type":"string","nullable":true},"is_multi_az":{"type":"boolean","nullable":true},"is_current_generation":{"type":"boolean","nullable":true},"license_model":{"type":"string","nullable":true},"pre_installed_sw":{"type":"string","nullable":true},"processor_architecture":{"type":"string","nullable":true},"is_reservable":{"type":"boolean","description":"Whether the SKU this resource is running has at least one reserved-term offering. Reservability is a property of the SKU, not the resource.","nullable":true},"is_byol":{"type":"boolean","description":"Whether the SKU is a Bring-Your-Own-License variant. Currently set for AWS RDS BYOL only; false elsewhere.","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the SKU is eligible for instance-size flexibility under reserved offerings (provider+service-specific rules — see `is_flexible` on the ResourceSKU model).","nullable":true},"is_serverless":{"type":"boolean","description":"Whether the SKU represents serverless usage.","nullable":true},"vcpu":{"type":"number","nullable":true},"memory":{"type":"number","description":"Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.","nullable":true},"ondemand_usage_unit":{"type":"string","nullable":true},"ondemand_usage_price":{"type":"number","description":"On-demand unit price in `price_currency`. List price from the catalog — this is NOT the user's actual spend for this resource (see ResourceSKUWithMetricsSchema's `total_cost` or /cost-explorer for that).","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_start":{"type":"string","format":"date-time","description":"Start of the period during which the resource was observed running this SKU. A resource that switched SKUs (e.g. instance-type resize) will have multiple ResourceSKU rows with disjoint `[usage_start, usage_end]` windows."},"usage_end":{"type":"string","format":"date-time","description":"End of the period during which the resource was observed running this SKU. Within ~2 days of now generally indicates the resource is currently active with this SKU."},"tags":{"type":"object","description":"Merged provider + user tags (user tags take precedence). Empty when the resource has no tags. Use the `untagged` filter to find resources with no tags at all.","additionalProperties":{"type":"string"},"nullable":true}},"additionalProperties":false}}}}
```

## The ResourceMatchDetail object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ResourceMatchDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Match identifier — stable per (plan, line item, resource) tuple. For the resource's own id, see `resource.id`."},"line_item_id":{"type":"string","format":"uuid","description":"Parent line item ID"},"projected_coverage":{"type":"number","description":"Spend-based fraction of this resource's usage THIS plan would cover (0-1). At this single-price resource-match granularity, the usage-unit and spend ratios are equivalent. Distinct from `resource.coverage`, which is trailing-30-day actual spend-based coverage from existing commitments (the BEFORE picture). For the cost-weighted group rollup, see the /covered-resources/summary endpoint."},"commitment_financials_monthly_rate":{"description":"Plan economics scoped to this resource, as 730-hour monthly rates. cloud_provider_cost has `{total}` only — per-match data doesn't have the recurring/amortized_upfront split. commitment_savings has no rebate field on plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"resource":{"description":"Detailed resource information including provider, service, region, instance type, account, and other infrastructure details","anyOf":[{"$ref":"#/components/schemas/ResourceSKU"},{"type":"object","nullable":true}]}},"required":["resource"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"ResourceSKU":{"type":"object","properties":{"id":{"type":"string","description":"Composite ResourceSKU id — `<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`. Pass directly to `/resources/skus/<id>` for detail; do not parse it client-side."},"resource_id":{"type":"string","format":"uuid","description":"Underlying Resource id. Stable across SKU/time variants of the same resource — multiple ResourceSKU rows can share a `resource_id` when the same resource ran with different SKUs over its lifetime."},"catalog_sku_id":{"type":"string","format":"uuid","description":"Join key into `/catalog/skus/<id>` for the public SKU record."},"catalog_sku_org_id":{"type":"string","description":"Org id that owns the catalog SKU — public-catalog SKUs use the public org id; custom-priced SKUs use the customer's org id."},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"provider_resource_id":{"type":"string","description":"Provider's id for the resource (AWS ARN, Azure resource ID, GCP resource name). This is the canonical identifier the user sees in the cloud console."},"provider_sku_id":{"type":"string","description":"Provider's own SKU identifier","nullable":true},"name":{"type":"string","description":"Resource name (Resource.name) — the user-applied label, e.g. 'prod-db-1'. Distinct from `sku_name`, which is the catalog SKU's display name.","nullable":true},"sku_name":{"type":"string","description":"Catalog SKU display name (e.g. 'Amazon EC2 Instance', 'Amazon Aurora PostgreSQL Cluster'). Useful as a fallback label when `instance_type_family` and `usage_type` are both null. Distinct from `name` (the resource's user-applied label).","nullable":true},"integration_id":{"type":"string","description":"Integration this resource belongs to"},"billing_account_id":{"type":"string","description":"Provider billing/management account id","nullable":true},"sub_account_id":{"type":"string","description":"Provider account id that owns/created the resource","nullable":true},"resource_group":{"type":"string","nullable":true},"is_spot":{"type":"boolean","nullable":true},"availability_zone":{"type":"string","nullable":true},"service":{"type":"string","description":"Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')","nullable":true},"provider_service":{"type":"string","description":"Provider service code (e.g. 'AmazonEC2')","nullable":true},"family":{"type":"string","description":"Product family (e.g. 'Compute Instance')","nullable":true},"region_code":{"type":"string","description":"Region code (e.g. 'us-east-1')","nullable":true},"full_region_name":{"type":"string","description":"Full region name (e.g. 'US East (N. Virginia)')","nullable":true},"instance_type":{"type":"string","nullable":true},"instance_type_family":{"type":"string","nullable":true},"usage_type":{"type":"string","description":"Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items.","nullable":true},"operation":{"type":"string","description":"Provider billing operation code (e.g. 'RunInstances:0002')","nullable":true},"operating_system":{"type":"string","nullable":true},"tenancy":{"type":"string","nullable":true},"database_engine":{"type":"string","nullable":true},"database_edition":{"type":"string","nullable":true},"cache_engine":{"type":"string","nullable":true},"is_multi_az":{"type":"boolean","nullable":true},"is_current_generation":{"type":"boolean","nullable":true},"license_model":{"type":"string","nullable":true},"pre_installed_sw":{"type":"string","nullable":true},"processor_architecture":{"type":"string","nullable":true},"is_reservable":{"type":"boolean","description":"Whether the SKU this resource is running has at least one reserved-term offering. Reservability is a property of the SKU, not the resource.","nullable":true},"is_byol":{"type":"boolean","description":"Whether the SKU is a Bring-Your-Own-License variant. Currently set for AWS RDS BYOL only; false elsewhere.","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the SKU is eligible for instance-size flexibility under reserved offerings (provider+service-specific rules — see `is_flexible` on the ResourceSKU model).","nullable":true},"is_serverless":{"type":"boolean","description":"Whether the SKU represents serverless usage.","nullable":true},"vcpu":{"type":"number","nullable":true},"memory":{"type":"number","description":"Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.","nullable":true},"ondemand_usage_unit":{"type":"string","nullable":true},"ondemand_usage_price":{"type":"number","description":"On-demand unit price in `price_currency`. List price from the catalog — this is NOT the user's actual spend for this resource (see ResourceSKUWithMetricsSchema's `total_cost` or /cost-explorer for that).","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_start":{"type":"string","format":"date-time","description":"Start of the period during which the resource was observed running this SKU. A resource that switched SKUs (e.g. instance-type resize) will have multiple ResourceSKU rows with disjoint `[usage_start, usage_end]` windows."},"usage_end":{"type":"string","format":"date-time","description":"End of the period during which the resource was observed running this SKU. Within ~2 days of now generally indicates the resource is currently active with this SKU."},"tags":{"type":"object","description":"Merged provider + user tags (user tags take precedence). Empty when the resource has no tags. Use the `untagged` filter to find resources with no tags at all.","additionalProperties":{"type":"string"},"nullable":true}},"additionalProperties":false}}}}
```

## The AutoPurchase object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"AutoPurchase":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the schedule is currently active"},"schedule":{"type":"string","enum":["daily","weekly","monthly"],"description":"Cadence: 'daily', 'weekly', or 'monthly'"},"min_monthly_savings":{"type":"number","description":"Dollar floor on projected monthly savings — plans that don't clear this are skipped even when the schedule fires."},"start_date":{"type":"string","format":"date","description":"Earliest date the automation may fire (inclusive). Null = no lower bound.","nullable":true},"end_date":{"type":"string","format":"date","description":"Latest date the automation may fire (inclusive). Null = no upper bound.","nullable":true},"next_execution_date":{"type":"string","format":"date","description":"When the next automated run is scheduled (computed)"},"last_executed_at":{"type":"string","format":"date-time","description":"When the last automated run fired, or null if it has not yet","nullable":true}},"required":["enabled","end_date","min_monthly_savings","schedule","start_date"],"additionalProperties":false}}}}
```

## The CommitmentPlanTemplate object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentPlanTemplate":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique template identifier"},"name":{"type":"string","description":"Human-readable template name"},"segment_id":{"type":"string","format":"uuid","description":"Segment this template generates plans for"},"created_at":{"type":"string","format":"date-time","description":"When the template was created"},"is_system_generated":{"type":"boolean","description":"True if this template was created automatically by the system — the three built-ins that back Recommended / Balanced / High Savings. Describes origin, not role — system-generated templates are immutable."},"configuration":{"description":"The inputs that plans generated from this template will use","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"auto_purchase":{"description":"Scheduled auto-purchase settings, or null if the template is not on a schedule.","anyOf":[{"$ref":"#/components/schemas/AutoPurchase"},{"type":"object","nullable":true}]}},"required":["auto_purchase","configuration","created_at","id","is_system_generated","name","segment_id"],"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"AutoPurchase":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the schedule is currently active"},"schedule":{"type":"string","enum":["daily","weekly","monthly"],"description":"Cadence: 'daily', 'weekly', or 'monthly'"},"min_monthly_savings":{"type":"number","description":"Dollar floor on projected monthly savings — plans that don't clear this are skipped even when the schedule fires."},"start_date":{"type":"string","format":"date","description":"Earliest date the automation may fire (inclusive). Null = no lower bound.","nullable":true},"end_date":{"type":"string","format":"date","description":"Latest date the automation may fire (inclusive). Null = no upper bound.","nullable":true},"next_execution_date":{"type":"string","format":"date","description":"When the next automated run is scheduled (computed)"},"last_executed_at":{"type":"string","format":"date-time","description":"When the last automated run fired, or null if it has not yet","nullable":true}},"required":["enabled","end_date","min_monthly_savings","schedule","start_date"],"additionalProperties":false}}}}
```

## The CreateAutoPurchase object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CreateAutoPurchase":{"type":"object","properties":{"schedule":{"type":"string","enum":["daily","weekly","monthly"],"description":"Cadence: 'daily', 'weekly', or 'monthly'"},"min_monthly_savings":{"type":"number","default":0,"description":"Dollar floor on projected monthly savings"},"enabled":{"type":"boolean","default":true,"description":"Whether the schedule is active"},"start_date":{"type":"string","format":"date","default":null,"description":"Earliest date automation may fire. Null = no lower bound.","nullable":true},"end_date":{"type":"string","format":"date","default":null,"description":"Latest date automation may fire. Null = no upper bound.","nullable":true}},"required":["schedule"],"additionalProperties":false}}}}
```

## The CreateCommitmentPlanTemplateArgs object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CreateCommitmentPlanTemplateArgs":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"segment_id":{"type":"string","format":"uuid","default":null,"description":"Optional segment ID to scope results. Defaults to the provider resources segment if not specified.","nullable":true},"name":{"type":"string","description":"Template name"},"configuration":{"description":"Plan configuration this template applies","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"auto_purchase":{"default":null,"description":"Optional auto-purchase schedule to attach","anyOf":[{"$ref":"#/components/schemas/CreateAutoPurchase"},{"type":"object","nullable":true}]}},"required":["configuration","name","provider"],"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"CreateAutoPurchase":{"type":"object","properties":{"schedule":{"type":"string","enum":["daily","weekly","monthly"],"description":"Cadence: 'daily', 'weekly', or 'monthly'"},"min_monthly_savings":{"type":"number","default":0,"description":"Dollar floor on projected monthly savings"},"enabled":{"type":"boolean","default":true,"description":"Whether the schedule is active"},"start_date":{"type":"string","format":"date","default":null,"description":"Earliest date automation may fire. Null = no lower bound.","nullable":true},"end_date":{"type":"string","format":"date","default":null,"description":"Latest date automation may fire. Null = no upper bound.","nullable":true}},"required":["schedule"],"additionalProperties":false}}}}
```

## The UpdateCommitmentPlanTemplateArgs object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"UpdateCommitmentPlanTemplateArgs":{"type":"object","properties":{"name":{"type":"string","description":"New template name"},"configuration":{"description":"Replacement configuration","allOf":[{"$ref":"#/components/schemas/CommitmentPlanConfiguration"}]},"auto_purchase":{"description":"Replacement schedule. Pass null to clear an existing schedule. Omit the key to leave the schedule untouched.","anyOf":[{"$ref":"#/components/schemas/CreateAutoPurchase"},{"type":"object","nullable":true}]}},"additionalProperties":false},"CommitmentPlanConfiguration":{"type":"object","properties":{"max_upfront_cost":{"type":"number","default":0,"description":"Cap on the one-time upfront dollars the generated plan is allowed to include. Defaults to 0 — the recommender excludes any line item with an upfront cost. Pass null to lift the cap entirely. Otherwise, line items with upfront costs are excluded if adding them would exceed the cap.","nullable":true},"lookback_days":{"type":"integer","default":null,"description":"How many days of historical usage to feed into plan generation. Defaults to 7 when omitted — matches the recommender's default and gives a representative recent-week baseline. Increase for workloads with weekly/seasonal variance. NULL on renewal plans: renewals derive their usage window from the source commitments' end dates, so this field has no effect. Sending a non-null value to a renewal plan PUT is rejected so round-tripping is honest.","nullable":true},"contract_specs":{"description":"List of contract specs to consider when generating the plan. Each spec is a triple of (commitment_type, contract_term, payment_option). The plan generator will pick the best mix of offerings matching these specs.","type":"array","items":{"$ref":"#/components/schemas/ConfigurationContractSpec"}},"resource_ids":{"type":"array","default":null,"description":"Optional list of resource composite ids (`<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`, the same form returned as `id` on resource-SKU responses) to scope the generated plan to specific resources. When non-empty, the plan's coverage is restricted to these resources and the plan is created as an infrastructure plan — line items only attempt to cover the listed resources rather than the whole segment. Mutually exclusive with `renewal_commitment_ids` (a plan can be scoped by resources OR scoped by renewing commitments, not both). Usually omitted; supply only when the user has explicitly named the resources to cover. Templates do not accept this field — supplying it on a template create/update is rejected.","items":{},"nullable":true},"renewal_commitment_ids":{"type":"array","default":null,"description":"Optional list of expiring commitment ids the plan is renewing. When non-empty, the plan is a renewal: coverage is built from the source commitments' historical usage, and each generated line item carries a `renewal_commitment_id` linking back to the source it proposes to replace. Mutually exclusive with `resource_ids`. On a renewal plan PUT this re-targets which commitments are being renewed (recalc); on a non-renewal plan PUT, sending this is rejected (use the dedicated POST /commitment-plans/renewals to create a renewal). Read-back unchanged from a GET so the configuration round-trips through PUT.","items":{"type":"string","format":"uuid"},"nullable":true}},"required":["contract_specs"],"additionalProperties":false},"ConfigurationContractSpec":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier — e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2', 'aws/AmazonRDS'. Values are provider-prefixed; fetch the exact list from GET /commitment-types and pass through verbatim. Rejected with 422 if the identifier is unknown across all providers; the validator does not enforce that the type belongs to the request's `provider` (a mismatched-but-real type will pass schema validation and produce a plan with no line items)."},"contract_term":{"description":"Commitment term (e.g. 'thirty_day_gris', 'one_year_gris', 'one_year', 'three_year'). Validated against the catalog entry for the supplied commitment_type — invalid (type, term) pairs are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront'). Validated against the catalog entry for the supplied (commitment_type, contract_term) pair — invalid triples are rejected with 422. Validation is cross-provider (see `commitment_type`).","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}},"required":["commitment_type","contract_term","payment_option"],"additionalProperties":false},"CreateAutoPurchase":{"type":"object","properties":{"schedule":{"type":"string","enum":["daily","weekly","monthly"],"description":"Cadence: 'daily', 'weekly', or 'monthly'"},"min_monthly_savings":{"type":"number","default":0,"description":"Dollar floor on projected monthly savings"},"enabled":{"type":"boolean","default":true,"description":"Whether the schedule is active"},"start_date":{"type":"string","format":"date","default":null,"description":"Earliest date automation may fire. Null = no lower bound.","nullable":true},"end_date":{"type":"string","format":"date","default":null,"description":"Latest date automation may fire. Null = no upper bound.","nullable":true}},"required":["schedule"],"additionalProperties":false}}}}
```

## The AvailableContractTerm object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"AvailableContractTerm":{"type":"object","properties":{"contract_term":{"type":"string","enum":["thirty_day_gris","one_year_gris","one_year","three_year","five_year"],"description":"Contract term identifier (e.g. 'one_year', 'three_year', 'thirty_day_gris'). Pass directly as `contract_term` in a plan's `configuration.contract_specs`."},"payment_options":{"type":"array","description":"Payment options available for this specific (commitment_type, contract_term) pair. Pass one as `payment_option` in the plan's contract spec.","items":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}}},"required":["contract_term","payment_options"],"additionalProperties":false}}}}
```

## The AvailableCommitmentType object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"AvailableCommitmentType":{"type":"object","properties":{"commitment_type":{"type":"string","description":"Commitment type identifier (e.g. 'aws/savingsplan/Compute', 'aws/AmazonEC2'). Pass directly as `commitment_type` in a plan's `configuration.contract_specs`."},"contract_terms":{"type":"array","description":"Contract terms this commitment type supports, each with its valid payment options. A `(contract_term, payment_option)` pair is only accepted in a plan spec if it appears here.","items":{"$ref":"#/components/schemas/AvailableContractTerm"}}},"required":["commitment_type","contract_terms"],"additionalProperties":false},"AvailableContractTerm":{"type":"object","properties":{"contract_term":{"type":"string","enum":["thirty_day_gris","one_year_gris","one_year","three_year","five_year"],"description":"Contract term identifier (e.g. 'one_year', 'three_year', 'thirty_day_gris'). Pass directly as `contract_term` in a plan's `configuration.contract_specs`."},"payment_options":{"type":"array","description":"Payment options available for this specific (commitment_type, contract_term) pair. Pass one as `payment_option` in the plan's contract spec.","items":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront"]}}},"required":["contract_term","payment_options"],"additionalProperties":false}}}}
```

## The CommitmentSavings object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false}}}}
```

## The CommitmentFinancials object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false}}}}
```

## The CommitmentWithMetrics object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentWithMetrics":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"utilization":{"type":"number","description":"Utilization rate (0-1) over the metrics period","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars paid at signing for this commitment. NOT a rate — do not sum with monthly-rate fields. 0 for commitments with no-upfront payment options."},"commitment_financials_monthly_rate":{"description":"Commitment economics as 730-hour monthly rates — cost, savings, and on-demand baseline. NOT a calendar month (672-744 hours). commitment_savings.rebate is populated with an actual value (possibly 0).","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false}}}}
```

## The BreakdownEntry object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"BreakdownEntry":{"type":"object","properties":{"label":{"type":"string","description":"Group label"},"count":{"type":"integer","description":"Number of commitments in this group"},"average_utilization":{"type":"number","description":"Cost-weighted average utilization within this group (0-1)"},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this group. commitment_savings.rebate is the sum of rebates for commitments in this group.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false}}}}
```

## The CommitmentSummary object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentSummary":{"type":"object","properties":{"total_commitments":{"type":"integer","description":"Total number of commitments in the summary scope. By default this includes active commitments and status=recently_expired commitments."},"total_active_commitments":{"type":"integer","description":"Number of commitments in the summary scope with is_active=true."},"recently_expired_commitments":{"type":"integer","description":"Number of commitments with status=recently_expired included in this summary scope. Zero when include_recently_expired=false."},"total_guaranteed_commitments":{"type":"integer","description":"Number of Archera Guaranteed Commitments in the summary scope"},"total_native_commitments":{"type":"integer","description":"Number of native cloud commitments (not guaranteed) in the summary scope"},"average_utilization":{"type":"number","description":"Cost-weighted average utilization across the summary scope (0-1)"},"expiring_30_days":{"type":"integer","description":"Number of commitments expiring in the next 30 days"},"expiring_90_days":{"type":"integer","description":"Number of commitments expiring in the next 90 days"},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials aggregated across the summary scope. commitment_savings.rebate is the sum of rebates across commitments.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"by_term":{"type":"array","description":"Breakdown by term length. Guaranteed commitments are grouped by their guarantee period (e.g. '30-Day Guaranteed', '1-Year Guaranteed'), native commitments by their cloud term (e.g. '1-Year Native', '3-Year Native').","items":{"$ref":"#/components/schemas/BreakdownEntry"}},"by_type":{"type":"array","description":"Breakdown by commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')","items":{"$ref":"#/components/schemas/BreakdownEntry"}}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"BreakdownEntry":{"type":"object","properties":{"label":{"type":"string","description":"Group label"},"count":{"type":"integer","description":"Number of commitments in this group"},"average_utilization":{"type":"number","description":"Cost-weighted average utilization within this group (0-1)"},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this group. commitment_savings.rebate is the sum of rebates for commitments in this group.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false}}}}
```

## The DailyUtilization object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of this data point"},"active_hours":{"type":"number","description":"Hours the commitment was active on this day (0-24)","nullable":true},"utilization":{"type":"number","description":"Utilization rate for this day (0-1)"},"commitment_financials_daily_total":{"description":"Sum of commitment economics for this single day (NOT a monthly rate). commitment_savings.rebate is the rebate accrued on this day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false}}}}
```

## The AttributionSummaryEntry object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"AttributionSummaryEntry":{"type":"object","properties":{"service":{"type":"string","description":"Cloud service name","nullable":true},"account_id":{"type":"string","description":"Cloud account ID","nullable":true},"region":{"type":"string","description":"Cloud region","nullable":true},"resource_type":{"type":"string","description":"Resource type — instance family for compute, usage type for other services, or SKU name as fallback","nullable":true},"resource_count":{"type":"integer","description":"Number of resources in this group"},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this group. cloud_provider_cost has `{total}` only — per-group data doesn't split into recurring / amortized_upfront. archera_premium is allocated proportionally by cloud_provider_cost share of the parent commitment; summing across groups yields the parent commitment's monthly premium. commitment_savings has no rebate field at this level — rebate is a commitment-wide concept.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"attributed_utilization":{"type":"number","description":"Share of the commitment's overall utilization attributed to this group (0-1). All groups' attributed_utilization values sum to the commitment's total utilization."}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The CoveredResourceEntry object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CoveredResourceEntry":{"type":"object","properties":{"resource_id":{"type":"string","description":"Archera resource id covered by this commitment."},"name":{"type":"string","description":"Display name of the resource. May be null.","nullable":true},"covered_usage":{"type":"number","description":"Sum of usage_amount_normalized this commitment covered on this resource over the period."},"total_usage":{"type":"number","description":"Sum of usage_amount_normalized across usage/commitment and usage/ondemand line items on this resource, restricted to the (resource, catalog SKU) pairs this commitment covered so the units match `covered_usage`."},"coverage_pct":{"type":"number","description":"Spend-based coverage: the on-demand-equivalent cost covered by this commitment divided by total on-demand-equivalent cost across the covered SKU pairs, in [0, 1]. 0 when total on-demand-equivalent cost is 0."}},"additionalProperties":false}}}}
```

## The CommitmentDetail object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"utilization":{"type":"number","description":"Utilization rate (0-1) over the metrics period","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars paid at signing for this commitment. NOT a rate — do not sum with monthly-rate fields. 0 for commitments with no-upfront payment options."},"commitment_financials_monthly_rate":{"description":"Commitment economics as 730-hour monthly rates — cost, savings, and on-demand baseline. NOT a calendar month (672-744 hours). commitment_savings.rebate is populated with an actual value (possibly 0).","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"daily_utilizations":{"type":"array","description":"Daily utilization data points for the effective time period","items":{"$ref":"#/components/schemas/DailyUtilization"}},"attribution_summary":{"type":"array","description":"Resources covered by this commitment, aggregated by service, account, region, and resource type","items":{"$ref":"#/components/schemas/AttributionSummaryEntry"}},"covered_resources":{"type":"array","description":"Per-resource breakdown of usage covered by this commitment over the period.","items":{"$ref":"#/components/schemas/CoveredResourceEntry"}}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"DailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of this data point"},"active_hours":{"type":"number","description":"Hours the commitment was active on this day (0-24)","nullable":true},"utilization":{"type":"number","description":"Utilization rate for this day (0-1)"},"commitment_financials_daily_total":{"description":"Sum of commitment economics for this single day (NOT a monthly rate). commitment_savings.rebate is the rebate accrued on this day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"AttributionSummaryEntry":{"type":"object","properties":{"service":{"type":"string","description":"Cloud service name","nullable":true},"account_id":{"type":"string","description":"Cloud account ID","nullable":true},"region":{"type":"string","description":"Cloud region","nullable":true},"resource_type":{"type":"string","description":"Resource type — instance family for compute, usage type for other services, or SKU name as fallback","nullable":true},"resource_count":{"type":"integer","description":"Number of resources in this group"},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for this group. cloud_provider_cost has `{total}` only — per-group data doesn't split into recurring / amortized_upfront. archera_premium is allocated proportionally by cloud_provider_cost share of the parent commitment; summing across groups yields the parent commitment's monthly premium. commitment_savings has no rebate field at this level — rebate is a commitment-wide concept.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"attributed_utilization":{"type":"number","description":"Share of the commitment's overall utilization attributed to this group (0-1). All groups' attributed_utilization values sum to the commitment's total utilization."}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CoveredResourceEntry":{"type":"object","properties":{"resource_id":{"type":"string","description":"Archera resource id covered by this commitment."},"name":{"type":"string","description":"Display name of the resource. May be null.","nullable":true},"covered_usage":{"type":"number","description":"Sum of usage_amount_normalized this commitment covered on this resource over the period."},"total_usage":{"type":"number","description":"Sum of usage_amount_normalized across usage/commitment and usage/ondemand line items on this resource, restricted to the (resource, catalog SKU) pairs this commitment covered so the units match `covered_usage`."},"coverage_pct":{"type":"number","description":"Spend-based coverage: the on-demand-equivalent cost covered by this commitment divided by total on-demand-equivalent cost across the covered SKU pairs, in [0, 1]. 0 when total on-demand-equivalent cost is 0."}},"additionalProperties":false}}}}
```

## The CommitmentOfferComparisonTotals object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentOfferComparisonTotals":{"type":"object","properties":{"commitment_financials_monthly_rate":{"description":"730-hour monthly rate financials summed across the commitments in scope. Same shape as on plans / line items. No-rebate basis to keep totals apples-to-apples with hypothetical_totals.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars at signing across the commitments in scope. NOT a rate — do not sum with monthly-rate fields."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The HypotheticalCommitmentDelta object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"HypotheticalCommitmentDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the portfolio does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The HypotheticalCommitmentEntry object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"HypotheticalCommitmentEntry":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"actual_term":{"description":"The contract term this commitment actually contributes to the rollup at. Equals the target when an exact match exists; otherwise the longest available term <= target with the same payment option, or the commitment's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this commitment contributes. Equals the target except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this commitment landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."},"utilization_warning":{"type":"boolean","description":"True if this commitment's recent utilization is below 50% — the comparison for it is less informative because candidates are sized from observed usage, not the commitment's nominal capacity. Surface to the user when present so the rollup is framed honestly."}},"required":["actual_payment_option","actual_term","actual_term_reason","commitment_id","utilization_warning"],"additionalProperties":false}}}}
```

## The HypotheticalCommitmentTotal object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"HypotheticalCommitmentTotal":{"type":"object","properties":{"contract_term":{"description":"Target contract term for this hypothetical.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Target payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"description":"Rolled-up monthly-rate financials assuming each commitment adopts its candidate per the fallback rule.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars across the commitments under this hypothetical. NOT a rate."},"delta_vs_current":{"description":"Axis-by-axis difference vs current_totals. The headline 'how much did I leave on the table' answer is delta_vs_current.monthly_net_savings.","allOf":[{"$ref":"#/components/schemas/HypotheticalCommitmentDelta"}]},"commitments":{"type":"array","description":"Per-commitment resolution for this hypothetical. Use to call out fallbacks ('14 of 20 commitments would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current') and underutilized-commitment caveats.","items":{"$ref":"#/components/schemas/HypotheticalCommitmentEntry"}},"low_utilization_commitment_count":{"type":"integer","description":"Number of commitments in this rollup whose recent utilization is below 50%. Convenience aggregate of the per-row utilization_warning flags. Surface when non-zero: the rollup deltas may overstate the savings opportunity since underutilized commitments project candidate savings against hours that aren't actually consumed."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","commitments","contract_term","delta_vs_current","low_utilization_commitment_count","payment_option"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"HypotheticalCommitmentDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the portfolio does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"HypotheticalCommitmentEntry":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"actual_term":{"description":"The contract term this commitment actually contributes to the rollup at. Equals the target when an exact match exists; otherwise the longest available term <= target with the same payment option, or the commitment's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this commitment contributes. Equals the target except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this commitment landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."},"utilization_warning":{"type":"boolean","description":"True if this commitment's recent utilization is below 50% — the comparison for it is less informative because candidates are sized from observed usage, not the commitment's nominal capacity. Surface to the user when present so the rollup is framed honestly."}},"required":["actual_payment_option","actual_term","actual_term_reason","commitment_id","utilization_warning"],"additionalProperties":false}}}}
```

## The CurrentCommitmentEntry object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CurrentCommitmentEntry":{"type":"object","properties":{"commitment":{"description":"Full identity of the existing commitment — id, provider, type, instance/region/account, dates, payment_option, contract_term, guarantee info. Same shape as `commitment_details`'s identity fields (no metrics).","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"utilization":{"type":"number","description":"Cost-weighted utilization rate (0-1) over the recent observation period the comparison is built against. The grid sizes candidates from observed usage, so utilization context matters for framing — low utilization means candidates reflect alternatives sized for actual usage, not for the commitment's original capacity.","nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1), NET basis (`(gross - premium) / on-demand`) — apples-to-apples with candidates."},"breakeven_days":{"type":"number","description":"Days until the existing commitment paid for itself, computed from upfront_cost and hourly net savings. Null if net savings are not positive.","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars paid at signing for this commitment. NOT a rate — do not sum with monthly-rate fields. 0 for no-upfront payment options."},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for the existing commitment in the no-rebate shape used by candidates. `commitment_savings.net` here is `gross - premium`, NOT including any rebate the commitment may be accruing — kept on the no-rebate basis so deltas vs candidates are apples-to-apples. For true current economics including rebate income, call `commitment_details`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The CandidateOfferEntry\_Exclude\_IsCurrent object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CandidateOfferEntry_Exclude_IsCurrent":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost).","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","allOf":[{"$ref":"#/components/schemas/OfferComparisonDelta"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":"number","description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven.","nullable":true}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The CommitmentOfferComparisonRow object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentOfferComparisonRow":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"current":{"description":"The existing commitment as the baseline — full identity, utilization, and current economics. Same shape as the singular tool's `current` block.","allOf":[{"$ref":"#/components/schemas/CurrentCommitmentEntry"}]},"candidates":{"type":"array","description":"Candidate offer alternatives sized for the same observed usage, filtered to the requested contract_terms and payment_options. Each candidate's delta_vs_current is per-COMMITMENT (NOT portfolio-wide). Sorted by net monthly savings, best first. May be empty when no valid replacements exist.","items":{"$ref":"#/components/schemas/CandidateOfferEntry_Exclude_IsCurrent"}}},"required":["candidates","commitment_id","current"],"additionalProperties":false},"CurrentCommitmentEntry":{"type":"object","properties":{"commitment":{"description":"Full identity of the existing commitment — id, provider, type, instance/region/account, dates, payment_option, contract_term, guarantee info. Same shape as `commitment_details`'s identity fields (no metrics).","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"utilization":{"type":"number","description":"Cost-weighted utilization rate (0-1) over the recent observation period the comparison is built against. The grid sizes candidates from observed usage, so utilization context matters for framing — low utilization means candidates reflect alternatives sized for actual usage, not for the commitment's original capacity.","nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1), NET basis (`(gross - premium) / on-demand`) — apples-to-apples with candidates."},"breakeven_days":{"type":"number","description":"Days until the existing commitment paid for itself, computed from upfront_cost and hourly net savings. Null if net savings are not positive.","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars paid at signing for this commitment. NOT a rate — do not sum with monthly-rate fields. 0 for no-upfront payment options."},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for the existing commitment in the no-rebate shape used by candidates. `commitment_savings.net` here is `gross - premium`, NOT including any rebate the commitment may be accruing — kept on the no-rebate basis so deltas vs candidates are apples-to-apples. For true current economics including rebate income, call `commitment_details`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CandidateOfferEntry_Exclude_IsCurrent":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost).","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","allOf":[{"$ref":"#/components/schemas/OfferComparisonDelta"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":"number","description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven.","nullable":true}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The SkippedCommitment object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"SkippedCommitment":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"reason":{"type":"string","description":"Why this commitment was skipped — typically 'no recent SKU usage' (commitment has no usage attributed to it in the recent observation window, so the candidate grid can't be built). Surface to the user rather than dropping silently."}},"required":["commitment_id","reason"],"additionalProperties":false}}}}
```

## The CommitmentOfferComparisonResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CommitmentOfferComparisonResponse":{"type":"object","properties":{"current_totals":{"description":"Portfolio-wide totals for the commitments currently in scope today. Use as the baseline when interpreting hypothetical deltas.","allOf":[{"$ref":"#/components/schemas/CommitmentOfferComparisonTotals"}]},"hypothetical_totals":{"type":"array","description":"One entry per (contract_term, payment_option) combination. Each entry's totals + delta_vs_current answer 'what's the portfolio-wide impact of this term?' in one place — no client-side summing across commitments required.","items":{"$ref":"#/components/schemas/HypotheticalCommitmentTotal"}},"data":{"type":"array","description":"Per-commitment detail. Use when the user wants to drill into a specific commitment's alternatives.","items":{"$ref":"#/components/schemas/CommitmentOfferComparisonRow"}},"skipped_commitments":{"type":"array","description":"Commitments that couldn't be compared (e.g. no recent SKU usage). Surface to the user so the rollup scope is honest — these commitments contribute neither to current_totals nor to hypothetical_totals.","items":{"$ref":"#/components/schemas/SkippedCommitment"}}},"required":["current_totals","data","hypothetical_totals","skipped_commitments"],"additionalProperties":false},"CommitmentOfferComparisonTotals":{"type":"object","properties":{"commitment_financials_monthly_rate":{"description":"730-hour monthly rate financials summed across the commitments in scope. Same shape as on plans / line items. No-rebate basis to keep totals apples-to-apples with hypothetical_totals.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars at signing across the commitments in scope. NOT a rate — do not sum with monthly-rate fields."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"HypotheticalCommitmentTotal":{"type":"object","properties":{"contract_term":{"description":"Target contract term for this hypothetical.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Target payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"description":"Rolled-up monthly-rate financials assuming each commitment adopts its candidate per the fallback rule.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Sum of one-time upfront dollars across the commitments under this hypothetical. NOT a rate."},"delta_vs_current":{"description":"Axis-by-axis difference vs current_totals. The headline 'how much did I leave on the table' answer is delta_vs_current.monthly_net_savings.","allOf":[{"$ref":"#/components/schemas/HypotheticalCommitmentDelta"}]},"commitments":{"type":"array","description":"Per-commitment resolution for this hypothetical. Use to call out fallbacks ('14 of 20 commitments would land at 3-year; 5 would fall back to 1-year GRI; 1 has no shorter alternative and stays at current') and underutilized-commitment caveats.","items":{"$ref":"#/components/schemas/HypotheticalCommitmentEntry"}},"low_utilization_commitment_count":{"type":"integer","description":"Number of commitments in this rollup whose recent utilization is below 50%. Convenience aggregate of the per-row utilization_warning flags. Surface when non-zero: the rollup deltas may overstate the savings opportunity since underutilized commitments project candidate savings against hours that aren't actually consumed."}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","commitments","contract_term","delta_vs_current","low_utilization_commitment_count","payment_option"],"additionalProperties":false},"HypotheticalCommitmentDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Hypothetical's monthly net savings minus current_totals'. Positive means switching saves more than the portfolio does today."},"monthly_commitment_cost":{"type":"number","description":"Hypothetical's monthly commitment cost minus current_totals'. Positive means more dollars committed monthly."},"upfront_cost":{"type":"number","description":"Hypothetical's one-time upfront cost minus current_totals'. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"HypotheticalCommitmentEntry":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"actual_term":{"description":"The contract term this commitment actually contributes to the rollup at. Equals the target when an exact match exists; otherwise the longest available term <= target with the same payment option, or the commitment's current term as a last resort.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the candidate this commitment contributes. Equals the target except when actual_term_reason='no_alternative' (falls back to current, which may have a different payment option).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this commitment landed at actual_term. exact_match = target available; fallback_closest_shorter = used the longest available term <= target with same payment option; no_alternative = nothing qualified, kept at current."},"utilization_warning":{"type":"boolean","description":"True if this commitment's recent utilization is below 50% — the comparison for it is less informative because candidates are sized from observed usage, not the commitment's nominal capacity. Surface to the user when present so the rollup is framed honestly."}},"required":["actual_payment_option","actual_term","actual_term_reason","commitment_id","utilization_warning"],"additionalProperties":false},"CommitmentOfferComparisonRow":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"current":{"description":"The existing commitment as the baseline — full identity, utilization, and current economics. Same shape as the singular tool's `current` block.","allOf":[{"$ref":"#/components/schemas/CurrentCommitmentEntry"}]},"candidates":{"type":"array","description":"Candidate offer alternatives sized for the same observed usage, filtered to the requested contract_terms and payment_options. Each candidate's delta_vs_current is per-COMMITMENT (NOT portfolio-wide). Sorted by net monthly savings, best first. May be empty when no valid replacements exist.","items":{"$ref":"#/components/schemas/CandidateOfferEntry_Exclude_IsCurrent"}}},"required":["candidates","commitment_id","current"],"additionalProperties":false},"CurrentCommitmentEntry":{"type":"object","properties":{"commitment":{"description":"Full identity of the existing commitment — id, provider, type, instance/region/account, dates, payment_option, contract_term, guarantee info. Same shape as `commitment_details`'s identity fields (no metrics).","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"utilization":{"type":"number","description":"Cost-weighted utilization rate (0-1) over the recent observation period the comparison is built against. The grid sizes candidates from observed usage, so utilization context matters for framing — low utilization means candidates reflect alternatives sized for actual usage, not for the commitment's original capacity.","nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1), NET basis (`(gross - premium) / on-demand`) — apples-to-apples with candidates."},"breakeven_days":{"type":"number","description":"Days until the existing commitment paid for itself, computed from upfront_cost and hourly net savings. Null if net savings are not positive.","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time total dollars paid at signing for this commitment. NOT a rate — do not sum with monthly-rate fields. 0 for no-upfront payment options."},"commitment_financials_monthly_rate":{"description":"730-hour monthly-rate financials for the existing commitment in the no-rebate shape used by candidates. `commitment_savings.net` here is `gross - premium`, NOT including any rebate the commitment may be accruing — kept on the no-rebate basis so deltas vs candidates are apples-to-apples. For true current economics including rebate income, call `commitment_details`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"CandidateOfferEntry_Exclude_IsCurrent":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Pass to PUT as `offer_id` to switch the line item to this offer."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for none. Pass to PUT as `lease_menu_item_id`.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Pass to PUT as `selected_amount`; the server routes it to the right underlying column based on offer type."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. '1_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). This is the real lock-in period, not the offer's raw duration — a Compute Savings Plan offer with a 3-year duration paired with a 1-year lease yields `one_year_gris`, not `three_year`. Prefer this field over `offer.duration_seconds` when describing term length.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1) for this candidate."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself. Null if breakeven is undefined (no net savings + no amortized cost).","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars required at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as on line items and plans.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"delta_vs_current":{"description":"Axis-by-axis difference vs the current offer. All zeros on the `is_current=true` entry.","allOf":[{"$ref":"#/components/schemas/OfferComparisonDelta"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_current","discount_rate","lease_menu_item_id","offer","offer_id","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"OfferComparisonDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Candidate's monthly net savings minus the current line item's."},"upfront_cost":{"type":"number","description":"Candidate's one-time upfront cost minus the current line item's. NOT a rate. Negative is less cash required at signing."},"discount_rate":{"type":"number","description":"Candidate's discount rate minus the current line item's (0-1 basis)."},"breakeven_days":{"type":"number","description":"Candidate's breakeven_days minus the current line item's. Null if either side has no finite breakeven.","nullable":true}},"required":["discount_rate","monthly_net_savings","upfront_cost"],"additionalProperties":false},"SkippedCommitment":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Commitment ID."},"reason":{"type":"string","description":"Why this commitment was skipped — typically 'no recent SKU usage' (commitment has no usage attributed to it in the recent observation window, so the candidate grid can't be built). Surface to the user rather than dropping silently."}},"required":["commitment_id","reason"],"additionalProperties":false}}}}
```

## The DailyMetricsDataPoint object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DailyMetricsDataPoint":{"type":"object","properties":{"date":{"type":"string","description":"Date (YYYY-MM-DD)"},"utilization":{"type":"number","description":"Cost-weighted utilization rate for this day (0-1)"},"underutilized_commitment_cost":{"type":"number","description":"Cost of unused/underutilized commitment capacity for this day"},"commitment_financials_daily_total":{"description":"Sum of commitment economics aggregated across commitments for this day. commitment_savings.rebate is the sum of per-commitment rebates for this day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false}}}}
```

## The MetricsResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"MetricsResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"utilization":{"type":"number","description":"Cost-weighted average utilization across the period (0-1)"},"underutilized_commitment_cost":{"type":"number","description":"Total cost of unused commitment capacity for the period"},"commitment_financials_period_total":{"description":"Sum of commitment economics aggregated across commitments over the requested date range. commitment_savings.rebate is the sum of per-commitment rebates for the period.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"data":{"type":"array","description":"Per-day data points for trend analysis","items":{"$ref":"#/components/schemas/DailyMetricsDataPoint"}}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"DailyMetricsDataPoint":{"type":"object","properties":{"date":{"type":"string","description":"Date (YYYY-MM-DD)"},"utilization":{"type":"number","description":"Cost-weighted utilization rate for this day (0-1)"},"underutilized_commitment_cost":{"type":"number","description":"Cost of unused/underutilized commitment capacity for this day"},"commitment_financials_daily_total":{"description":"Sum of commitment economics aggregated across commitments for this day. commitment_savings.rebate is the sum of per-commitment rebates for this day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false}}}}
```

## The RecommendedAction object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"RecommendedAction":{"type":"object","properties":{"action":{"type":"string","description":"Action identifier (e.g. 'apply_recommended_plan')"},"description":{"type":"string","description":"Human-readable description of the recommended action"},"monthly_impact":{"type":"number","description":"Estimated monthly savings impact if action is taken","nullable":true},"priority":{"type":"string","description":"Priority level: 'high', 'medium', or 'low'"}},"additionalProperties":false}}}}
```

## The Overview object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"Overview":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Current monthly net savings rate from active commitments"},"expiring_monthly_savings":{"type":"number","description":"Monthly savings at risk from commitments expiring in the next 30 days"},"coverage":{"type":"number","description":"Overall spend-based commitment coverage ratio (0-1): share of reservable on-demand-equivalent spend covered, not the share of hours or usage units.","nullable":true},"utilization":{"type":"number","description":"Overall commitment utilization ratio (0-1)","nullable":true},"purchase_missed_savings":{"type":"number","description":"Monthly savings available by applying the recommended commitment plan. 0 if a plan has already been applied."},"buyback_missed_savings":{"type":"number","description":"Monthly savings available from pending buyback opportunities"},"purchase_automation_enabled":{"type":"boolean","description":"Whether automatic commitment purchasing is enabled"},"buyback_automation_enabled":{"type":"boolean","description":"Whether automatic buyback/sellback is enabled"},"has_actioned_plan":{"type":"boolean","description":"Whether the organization has ever applied a commitment plan"},"data_available_since":{"type":"string","format":"date","description":"Earliest date cost data is available for this provider (null if no data)","nullable":true},"recommended_actions":{"type":"array","description":"Prioritized list of recommended actions to improve savings","items":{"$ref":"#/components/schemas/RecommendedAction"}}},"additionalProperties":false},"RecommendedAction":{"type":"object","properties":{"action":{"type":"string","description":"Action identifier (e.g. 'apply_recommended_plan')"},"description":{"type":"string","description":"Human-readable description of the recommended action"},"monthly_impact":{"type":"number","description":"Estimated monthly savings impact if action is taken","nullable":true},"priority":{"type":"string","description":"Priority level: 'high', 'medium', or 'low'"}},"additionalProperties":false}}}}
```

## The DailyCoveragePoint object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DailyCoveragePoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"coverage":{"type":"number","description":"Spend-based commitment coverage for this day (0-1)."}},"additionalProperties":false}}}}
```

## The DailyCoverageGroup object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DailyCoverageGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (service name, account ID, or region)."},"coverage":{"type":"number","description":"Spend-based commitment coverage for this group across the range (0-1), weighted by each day's reservable on-demand-equivalent spend.","nullable":true},"daily":{"type":"array","description":"Per-day coverage values for this group.","items":{"$ref":"#/components/schemas/DailyCoveragePoint"}}},"additionalProperties":false},"DailyCoveragePoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"coverage":{"type":"number","description":"Spend-based commitment coverage for this day (0-1)."}},"additionalProperties":false}}}}
```

## The DailyCoverageResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DailyCoverageResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"coverage":{"type":"number","description":"Spend-based commitment coverage across the effective date range (0-1): the share of reservable on-demand-equivalent spend covered by commitments, weighted by each day's spend rather than hours or usage units.","nullable":true},"daily":{"type":"array","description":"Per-day data points for trend analysis.","items":{"$ref":"#/components/schemas/DailyCoveragePoint"}},"groups":{"type":"array","description":"Grouped coverage series. Null when group_by is omitted; otherwise one entry per service, account, or region. Empty when group_by is set but no groups match.","items":{"$ref":"#/components/schemas/DailyCoverageGroup"},"nullable":true}},"additionalProperties":false},"DailyCoveragePoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"coverage":{"type":"number","description":"Spend-based commitment coverage for this day (0-1)."}},"additionalProperties":false},"DailyCoverageGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (service name, account ID, or region)."},"coverage":{"type":"number","description":"Spend-based commitment coverage for this group across the range (0-1), weighted by each day's reservable on-demand-equivalent spend.","nullable":true},"daily":{"type":"array","description":"Per-day coverage values for this group.","items":{"$ref":"#/components/schemas/DailyCoveragePoint"}}},"additionalProperties":false}}}}
```

## The DailySavingsPoint object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DailySavingsPoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"commitment_financials_daily_total":{"description":"Sum of commitment economics for this single day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The DailySavingsGroup object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DailySavingsGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (service name, account ID, or region)."},"commitment_financials_period_total":{"description":"Sum of commitment economics for this group over the range.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"daily":{"type":"array","description":"Per-day savings values for this group.","items":{"$ref":"#/components/schemas/DailySavingsPoint"}}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"DailySavingsPoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"commitment_financials_daily_total":{"description":"Sum of commitment economics for this single day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"additionalProperties":false}}}}
```

## The DailySavingsResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DailySavingsResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"commitment_financials_period_total":{"description":"Sum of commitment economics across the effective date range.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"daily":{"type":"array","description":"Per-day data points for trend analysis.","items":{"$ref":"#/components/schemas/DailySavingsPoint"}},"groups":{"type":"array","description":"Grouped savings series. Null when group_by is omitted; otherwise one entry per service, account, or region. Empty when group_by is set but no groups match.","items":{"$ref":"#/components/schemas/DailySavingsGroup"},"nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"DailySavingsPoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"commitment_financials_daily_total":{"description":"Sum of commitment economics for this single day.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"additionalProperties":false},"DailySavingsGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (service name, account ID, or region)."},"commitment_financials_period_total":{"description":"Sum of commitment economics for this group over the range.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"daily":{"type":"array","description":"Per-day savings values for this group.","items":{"$ref":"#/components/schemas/DailySavingsPoint"}}},"additionalProperties":false}}}}
```

## The PricingTypeBreakdown object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"PricingTypeBreakdown":{"type":"object","properties":{"ondemand_cost":{"type":"number","description":"Cost from uncovered usage."},"commitment_cost":{"description":"Total cost from commitment-covered usage, with breakdown into cloud provider portion and Archera premium.","allOf":[{"$ref":"#/components/schemas/CommitmentCost"}]}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false}}}}
```

## The DailyReservableCostPoint object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DailyReservableCostPoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"total_cost":{"type":"number","description":"Total paid for reservable services this day across uncovered and commitment-covered pricing (ondemand_cost + commitment_cost.total). Headline 'cost'."},"if_all_ondemand_cost":{"type":"number","description":"What total_cost would be if all reservable usage ran at on-demand prices. Baseline for total savings across all discount types."},"by_pricing_type":{"$ref":"#/components/schemas/PricingTypeBreakdown"}},"additionalProperties":false},"PricingTypeBreakdown":{"type":"object","properties":{"ondemand_cost":{"type":"number","description":"Cost from uncovered usage."},"commitment_cost":{"description":"Total cost from commitment-covered usage, with breakdown into cloud provider portion and Archera premium.","allOf":[{"$ref":"#/components/schemas/CommitmentCost"}]}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false}}}}
```

## The DailyReservableCostGroup object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DailyReservableCostGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (service name, account ID, or region)."},"total_cost":{"type":"number","description":"Total paid for reservable services in this group."},"if_all_ondemand_cost":{"type":"number","description":"On-demand baseline for this group's reservable services."},"total_savings":{"type":"number","description":"Total savings for this group across all discount types (if_all_ondemand_cost - total_cost)."},"by_pricing_type":{"$ref":"#/components/schemas/PricingTypeBreakdown"},"daily":{"type":"array","description":"Per-day cost values for this group.","items":{"$ref":"#/components/schemas/DailyReservableCostPoint"}}},"additionalProperties":false},"PricingTypeBreakdown":{"type":"object","properties":{"ondemand_cost":{"type":"number","description":"Cost from uncovered usage."},"commitment_cost":{"description":"Total cost from commitment-covered usage, with breakdown into cloud provider portion and Archera premium.","allOf":[{"$ref":"#/components/schemas/CommitmentCost"}]}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"DailyReservableCostPoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"total_cost":{"type":"number","description":"Total paid for reservable services this day across uncovered and commitment-covered pricing (ondemand_cost + commitment_cost.total). Headline 'cost'."},"if_all_ondemand_cost":{"type":"number","description":"What total_cost would be if all reservable usage ran at on-demand prices. Baseline for total savings across all discount types."},"by_pricing_type":{"$ref":"#/components/schemas/PricingTypeBreakdown"}},"additionalProperties":false}}}}
```

## The DailyReservableCostResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"DailyReservableCostResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"total_cost":{"type":"number","description":"Total paid for reservable services over the effective date range."},"if_all_ondemand_cost":{"type":"number","description":"On-demand baseline: what the range would cost at on-demand prices."},"total_savings":{"type":"number","description":"Total savings across all discount types (if_all_ondemand_cost - total_cost)."},"by_pricing_type":{"$ref":"#/components/schemas/PricingTypeBreakdown"},"daily":{"type":"array","description":"Per-day data points for trend analysis.","items":{"$ref":"#/components/schemas/DailyReservableCostPoint"}},"groups":{"type":"array","description":"Grouped reservable-cost series. Null when group_by is omitted; otherwise one entry per service, account, or region. Empty when group_by is set but no groups match.","items":{"$ref":"#/components/schemas/DailyReservableCostGroup"},"nullable":true}},"additionalProperties":false},"PricingTypeBreakdown":{"type":"object","properties":{"ondemand_cost":{"type":"number","description":"Cost from uncovered usage."},"commitment_cost":{"description":"Total cost from commitment-covered usage, with breakdown into cloud provider portion and Archera premium.","allOf":[{"$ref":"#/components/schemas/CommitmentCost"}]}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"DailyReservableCostPoint":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date of data point"},"total_cost":{"type":"number","description":"Total paid for reservable services this day across uncovered and commitment-covered pricing (ondemand_cost + commitment_cost.total). Headline 'cost'."},"if_all_ondemand_cost":{"type":"number","description":"What total_cost would be if all reservable usage ran at on-demand prices. Baseline for total savings across all discount types."},"by_pricing_type":{"$ref":"#/components/schemas/PricingTypeBreakdown"}},"additionalProperties":false},"DailyReservableCostGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (service name, account ID, or region)."},"total_cost":{"type":"number","description":"Total paid for reservable services in this group."},"if_all_ondemand_cost":{"type":"number","description":"On-demand baseline for this group's reservable services."},"total_savings":{"type":"number","description":"Total savings for this group across all discount types (if_all_ondemand_cost - total_cost)."},"by_pricing_type":{"$ref":"#/components/schemas/PricingTypeBreakdown"},"daily":{"type":"array","description":"Per-day cost values for this group.","items":{"$ref":"#/components/schemas/DailyReservableCostPoint"}}},"additionalProperties":false}}}}
```

## The MoneybackGuaranteeMonthlySavings object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"MoneybackGuaranteeMonthlySavings":{"type":"object","properties":{"monthly_rebate_savings":{"type":"number","description":"Rebates delivered over the requested period, normalized to a 730-hour monthly rate"},"monthly_release_savings":{"type":"number","description":"730-hour monthly commitment cost eliminated by commitments resold during the requested period"},"monthly_total_savings":{"type":"number","description":"Sum of monthly_rebate_savings and monthly_release_savings"}},"additionalProperties":false}}}}
```

## The Segment object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"Segment":{"type":"object","properties":{"id":{"type":"string","description":"Unique segment identifier"},"name":{"type":"string","description":"Segment name"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"is_system_generated":{"type":"boolean","description":"True if this segment was created automatically by the system (e.g. the provider-resources default segment). Describes origin, not role — system-generated segments are immutable."},"description":{"type":"string","description":"Human-readable description of the segment","nullable":true},"status":{"description":"Segment status: 'new' means the segment was just created and metrics data is not yet available; 'completed' means data has been populated and the segment can be used with daily metrics endpoints.","type":"string","enum":["new","reviewed","scheduled","completed","draft","needs_review","in_progress"]},"filters":{"readOnly":true,"description":"The segment's filter configuration, in the same format accepted by create_segment. Excludes the provider filter (already shown in the provider field)."},"monthly_budget":{"type":"number","description":"User-defined monthly spend budget for this segment, in USD. Null if no budget has been set.","nullable":true}},"additionalProperties":false}}}}
```

## The CreateSegmentArgs object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CreateSegmentArgs":{"type":"object","properties":{"name":{"type":"string","description":"Segment name"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"filters":{"type":"object","description":"Filter tree using and/or/not combinators with field/op/value leaves. Use `has` on `tags` with nested key/value filters for tag matches. The provider filter is injected automatically.","additionalProperties":{}},"description":{"type":"string","default":null,"description":"Human-readable description","nullable":true}},"required":["filters","name","provider"],"additionalProperties":false}}}}
```

## The PremiumDiscount object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"PremiumDiscount":{"type":"object","properties":{"rate":{"type":"number","description":"Discount rate (0-1, usually 0)."},"amount":{"type":"number","description":"Dollars removed by the discount. Equals list_price * rate."}},"additionalProperties":false}}}}
```

## The PremiumBilling object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"PremiumBilling":{"type":"object","properties":{"charged":{"type":"number","description":"Premium actually charged on the bill — post-discount, post-credits. Headline: 'how much the user paid Archera for this billing scope.'"},"list_price":{"type":"number","description":"Pre-discount, pre-credits premium. Starting point of the billing waterfall."},"discount":{"description":"Discount applied to the list price (rate and precomputed amount).","allOf":[{"$ref":"#/components/schemas/PremiumDiscount"}]},"credits_applied":{"type":"number","description":"Credits (from rebates or other sources) applied to reduce the premium."}},"additionalProperties":false},"PremiumDiscount":{"type":"object","properties":{"rate":{"type":"number","description":"Discount rate (0-1, usually 0)."},"amount":{"type":"number","description":"Dollars removed by the discount. Equals list_price * rate."}},"additionalProperties":false}}}}
```

## The InvoiceSectionList object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"InvoiceSectionList":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"commitment_financials_invoice_month":{"description":"Aggregated list-price figures for this provider over the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"premium_billing":{"description":"Premium waterfall for this provider — list_price, discount, credits_applied, and the charged amount that hits the bill. `charged` is the answer to 'what did the user actually pay Archera for this provider' — not the archera_premium inside commitment_financials_invoice_month, which is list-price.","allOf":[{"$ref":"#/components/schemas/PremiumBilling"}]},"total_cloud_bill":{"type":"number","description":"Total cloud provider bill for this period, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)"}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"PremiumBilling":{"type":"object","properties":{"charged":{"type":"number","description":"Premium actually charged on the bill — post-discount, post-credits. Headline: 'how much the user paid Archera for this billing scope.'"},"list_price":{"type":"number","description":"Pre-discount, pre-credits premium. Starting point of the billing waterfall."},"discount":{"description":"Discount applied to the list price (rate and precomputed amount).","allOf":[{"$ref":"#/components/schemas/PremiumDiscount"}]},"credits_applied":{"type":"number","description":"Credits (from rebates or other sources) applied to reduce the premium."}},"additionalProperties":false},"PremiumDiscount":{"type":"object","properties":{"rate":{"type":"number","description":"Discount rate (0-1, usually 0)."},"amount":{"type":"number","description":"Dollars removed by the discount. Equals list_price * rate."}},"additionalProperties":false}}}}
```

## The InvoiceList object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"InvoiceList":{"type":"object","properties":{"id":{"type":"string","description":"Invoice identifier"},"year":{"type":"integer","description":"Invoice year"},"month":{"type":"integer","description":"Invoice month (1-12)"},"invoice_date":{"type":"string","format":"date","description":"Invoice date (first of the month)"},"commitment_financials_invoice_month":{"description":"Aggregated list-price figures across all providers for the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items/sections); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"premium_billing":{"description":"Premium waterfall across all providers — list_price, discount, credits_applied, and the charged amount. `premium_billing.charged` is the answer to 'how much did I pay Archera this month' — not the archera_premium inside commitment_financials_invoice_month, which is list-price.","allOf":[{"$ref":"#/components/schemas/PremiumBilling"}]},"total_cloud_bill":{"readOnly":true,"description":"Total cloud provider bill across all providers, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)."},"sections":{"description":"Per-provider breakdown of the invoice","type":"array","items":{"$ref":"#/components/schemas/InvoiceSectionList"}}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"PremiumBilling":{"type":"object","properties":{"charged":{"type":"number","description":"Premium actually charged on the bill — post-discount, post-credits. Headline: 'how much the user paid Archera for this billing scope.'"},"list_price":{"type":"number","description":"Pre-discount, pre-credits premium. Starting point of the billing waterfall."},"discount":{"description":"Discount applied to the list price (rate and precomputed amount).","allOf":[{"$ref":"#/components/schemas/PremiumDiscount"}]},"credits_applied":{"type":"number","description":"Credits (from rebates or other sources) applied to reduce the premium."}},"additionalProperties":false},"PremiumDiscount":{"type":"object","properties":{"rate":{"type":"number","description":"Discount rate (0-1, usually 0)."},"amount":{"type":"number","description":"Dollars removed by the discount. Equals list_price * rate."}},"additionalProperties":false},"InvoiceSectionList":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"commitment_financials_invoice_month":{"description":"Aggregated list-price figures for this provider over the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"premium_billing":{"description":"Premium waterfall for this provider — list_price, discount, credits_applied, and the charged amount that hits the bill. `charged` is the answer to 'what did the user actually pay Archera for this provider' — not the archera_premium inside commitment_financials_invoice_month, which is list-price.","allOf":[{"$ref":"#/components/schemas/PremiumBilling"}]},"total_cloud_bill":{"type":"number","description":"Total cloud provider bill for this period, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)"}},"additionalProperties":false}}}}
```

## The InvoiceBreakdown object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"InvoiceBreakdown":{"type":"object","properties":{"label":{"type":"string","description":"Group label"},"count":{"type":"integer","description":"Number of line items in this group"},"commitment_financials_invoice_month":{"description":"Aggregated list-price invoice-month financials for this group. commitment_cost.breakdown.archera_premium is list-price, matching line-item/section/invoice aggregation.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false}}}}
```

## The InvoiceSection object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"InvoiceSection":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"commitment_financials_invoice_month":{"description":"Aggregated list-price figures for this provider over the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"premium_billing":{"description":"Premium waterfall for this provider — list_price, discount, credits_applied, and the charged amount that hits the bill. `charged` is the answer to 'what did the user actually pay Archera for this provider' — not the archera_premium inside commitment_financials_invoice_month, which is list-price.","allOf":[{"$ref":"#/components/schemas/PremiumBilling"}]},"total_cloud_bill":{"type":"number","description":"Total cloud provider bill for this period, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)"},"by_term":{"type":"array","description":"This provider section's invoice-month metrics broken down by contract term (from `InvoiceLineItem.contract_term`). GRI labels = Archera Guaranteed; Commitment labels = native cloud commitments. Sum across GRI labels for the insured view, across Commitment labels for the uninsured view.","items":{"$ref":"#/components/schemas/InvoiceBreakdown"}},"by_type":{"type":"array","description":"This provider section's invoice-month metrics broken down by commitment type (e.g. 'Compute', 'EC2Instance', 'RDS').","items":{"$ref":"#/components/schemas/InvoiceBreakdown"}}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"PremiumBilling":{"type":"object","properties":{"charged":{"type":"number","description":"Premium actually charged on the bill — post-discount, post-credits. Headline: 'how much the user paid Archera for this billing scope.'"},"list_price":{"type":"number","description":"Pre-discount, pre-credits premium. Starting point of the billing waterfall."},"discount":{"description":"Discount applied to the list price (rate and precomputed amount).","allOf":[{"$ref":"#/components/schemas/PremiumDiscount"}]},"credits_applied":{"type":"number","description":"Credits (from rebates or other sources) applied to reduce the premium."}},"additionalProperties":false},"PremiumDiscount":{"type":"object","properties":{"rate":{"type":"number","description":"Discount rate (0-1, usually 0)."},"amount":{"type":"number","description":"Dollars removed by the discount. Equals list_price * rate."}},"additionalProperties":false},"InvoiceBreakdown":{"type":"object","properties":{"label":{"type":"string","description":"Group label"},"count":{"type":"integer","description":"Number of line items in this group"},"commitment_financials_invoice_month":{"description":"Aggregated list-price invoice-month financials for this group. commitment_cost.breakdown.archera_premium is list-price, matching line-item/section/invoice aggregation.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false}}}}
```

## The Invoice object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"Invoice":{"type":"object","properties":{"id":{"type":"string","description":"Invoice identifier"},"year":{"type":"integer","description":"Invoice year"},"month":{"type":"integer","description":"Invoice month (1-12)"},"invoice_date":{"type":"string","format":"date","description":"Invoice date (first of the month)"},"commitment_financials_invoice_month":{"description":"Aggregated list-price figures across all providers for the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items/sections); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"premium_billing":{"description":"Premium waterfall across all providers — list_price, discount, credits_applied, and the charged amount. `premium_billing.charged` is the answer to 'how much did I pay Archera this month' — not the archera_premium inside commitment_financials_invoice_month, which is list-price.","allOf":[{"$ref":"#/components/schemas/PremiumBilling"}]},"total_cloud_bill":{"readOnly":true,"description":"Total cloud provider bill across all providers, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)."},"sections":{"description":"Per-provider breakdown of the invoice","type":"array","items":{"$ref":"#/components/schemas/InvoiceSection"}},"by_term":{"type":"array","description":"Invoice-month metrics across all providers broken down by contract term (from `InvoiceLineItem.contract_term`). GRI labels = Archera Guaranteed; Commitment labels = native cloud commitments. Sum across GRI labels for the insured view, across Commitment labels for the uninsured view.","items":{"$ref":"#/components/schemas/InvoiceBreakdown"}},"by_type":{"type":"array","description":"Invoice-month metrics across all providers broken down by commitment type (e.g. 'Compute', 'EC2Instance', 'RDS').","items":{"$ref":"#/components/schemas/InvoiceBreakdown"}}},"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false},"PremiumBilling":{"type":"object","properties":{"charged":{"type":"number","description":"Premium actually charged on the bill — post-discount, post-credits. Headline: 'how much the user paid Archera for this billing scope.'"},"list_price":{"type":"number","description":"Pre-discount, pre-credits premium. Starting point of the billing waterfall."},"discount":{"description":"Discount applied to the list price (rate and precomputed amount).","allOf":[{"$ref":"#/components/schemas/PremiumDiscount"}]},"credits_applied":{"type":"number","description":"Credits (from rebates or other sources) applied to reduce the premium."}},"additionalProperties":false},"PremiumDiscount":{"type":"object","properties":{"rate":{"type":"number","description":"Discount rate (0-1, usually 0)."},"amount":{"type":"number","description":"Dollars removed by the discount. Equals list_price * rate."}},"additionalProperties":false},"InvoiceSection":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"commitment_financials_invoice_month":{"description":"Aggregated list-price figures for this provider over the invoice's calendar month. commitment_cost.breakdown.archera_premium is the list-price premium (sums cleanly from line items); commitment_savings.net is the pre-invoice-adjustments view (gross - list_price + rebate). For the real charged premium and the discount/credits waterfall, see `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]},"premium_billing":{"description":"Premium waterfall for this provider — list_price, discount, credits_applied, and the charged amount that hits the bill. `charged` is the answer to 'what did the user actually pay Archera for this provider' — not the archera_premium inside commitment_financials_invoice_month, which is list-price.","allOf":[{"$ref":"#/components/schemas/PremiumBilling"}]},"total_cloud_bill":{"type":"number","description":"Total cloud provider bill for this period, before applying any credits or enterprise discounts (AWS EDP/PPA, Azure MACC, GCP commit agreements)"},"by_term":{"type":"array","description":"This provider section's invoice-month metrics broken down by contract term (from `InvoiceLineItem.contract_term`). GRI labels = Archera Guaranteed; Commitment labels = native cloud commitments. Sum across GRI labels for the insured view, across Commitment labels for the uninsured view.","items":{"$ref":"#/components/schemas/InvoiceBreakdown"}},"by_type":{"type":"array","description":"This provider section's invoice-month metrics broken down by commitment type (e.g. 'Compute', 'EC2Instance', 'RDS').","items":{"$ref":"#/components/schemas/InvoiceBreakdown"}}},"additionalProperties":false},"InvoiceBreakdown":{"type":"object","properties":{"label":{"type":"string","description":"Group label"},"count":{"type":"integer","description":"Number of line items in this group"},"commitment_financials_invoice_month":{"description":"Aggregated list-price invoice-month financials for this group. commitment_cost.breakdown.archera_premium is list-price, matching line-item/section/invoice aggregation.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false}}}}
```

## The InvoiceLineItem object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"InvoiceLineItem":{"type":"object","properties":{"id":{"type":"string","description":"Line item identifier"},"commitment_id":{"type":"string","description":"Associated commitment identifier"},"commitment":{"description":"Full commitment details (identity, dates, guarantee info, region/instance info, contract term). Metrics (utilization/financials) aren't included here — this invoice line item has its own financials.","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"utilization":{"type":"number","description":"Average utilization for this commitment during the invoice period (0-1)"},"contract_term":{"description":"Contract term of the commitment as it applied during this invoice's billing month — reflects the guarantee lock-in in effect at bill time. Prefer this over `commitment.contract_term`, which reflects the commitment's current term and may have shifted since (e.g. lock-in rolled over, guarantee changed).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"commitment_financials_invoice_month":{"description":"Actual dollars billed for this line item over the invoice's calendar month. commitment_cost.breakdown.archera_premium is this line item's list-price premium — invoice-wide discount/credits don't attribute per-commitment, so there's no line-item charged value. For the real charged premium on the bill and the full waterfall (list_price, discount, credits), see the parent section's or invoice's `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancials":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."},"rebate":{"type":"number","description":"Recovery from Archera's moneyback guarantee. Non-zero only for guaranteed commitments past their lock-in date that are underperforming. Present only on commitment-level endpoints (inventory, detail, invoice line items, and commitment-level aggregates like commitments_metrics / commitments_summary) — 0 when the commitment(s) have no rebate. Omitted entirely on plans and segment-level metrics. Already included in `net` when present."}},"additionalProperties":false}}}}
```

## The CostExplorerDataPoint object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CostExplorerDataPoint":{"type":"object","properties":{"date":{"type":"string","description":"Date or month label for this data point"},"cost":{"type":"number","description":"Cost for this period"}},"additionalProperties":false}}}}
```

## The CostExplorerGroup object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CostExplorerGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (e.g. service name, account ID, region)"},"total_cost":{"type":"number","description":"Total cost for this group over the entire period"},"percentage":{"type":"number","description":"This group's share of total spend (0-1)"},"data":{"type":"array","default":null,"description":"Time-series data points for this group. Only included when include_time_series=true.","items":{"$ref":"#/components/schemas/CostExplorerDataPoint"},"nullable":true}},"additionalProperties":false},"CostExplorerDataPoint":{"type":"object","properties":{"date":{"type":"string","description":"Date or month label for this data point"},"cost":{"type":"number","description":"Cost for this period"}},"additionalProperties":false}}}}
```

## The CostExplorerResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CostExplorerResponse":{"type":"object","properties":{"period_start":{"type":"string","description":"Effective start date of the returned data (YYYY-MM-DD). May be later than the requested start_date if the range was clamped to available data."},"period_end":{"type":"string","description":"Effective end date of the returned data, exclusive (YYYY-MM-DD). May be earlier than the requested end_date if the range was clamped to available data (e.g. cloud-provider cost-data lag)."},"total_cost":{"type":"number","description":"Total cost across all groups over the effective date range. Headline 'cost' — the answer to 'what did I spend.' Sum of groups[*].total_cost."},"groups":{"type":"array","description":"Cost groups, sorted by total spend descending","items":{"$ref":"#/components/schemas/CostExplorerGroup"}}},"additionalProperties":false},"CostExplorerGroup":{"type":"object","properties":{"name":{"type":"string","description":"Group name (e.g. service name, account ID, region)"},"total_cost":{"type":"number","description":"Total cost for this group over the entire period"},"percentage":{"type":"number","description":"This group's share of total spend (0-1)"},"data":{"type":"array","default":null,"description":"Time-series data points for this group. Only included when include_time_series=true.","items":{"$ref":"#/components/schemas/CostExplorerDataPoint"},"nullable":true}},"additionalProperties":false},"CostExplorerDataPoint":{"type":"object","properties":{"date":{"type":"string","description":"Date or month label for this data point"},"cost":{"type":"number","description":"Cost for this period"}},"additionalProperties":false}}}}
```

## The CostExplorerFilters object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CostExplorerFilters":{"type":"object","properties":{"service":{"type":"array","description":"Available cloud service names","items":{"type":"string"}},"account_id":{"type":"array","description":"Available cloud account IDs","items":{"type":"string"}},"region":{"type":"array","description":"Available cloud regions","items":{"type":"string"}},"instance_family":{"type":"array","description":"Available instance families (AWS only)","items":{"type":"string"}},"operating_system":{"type":"array","description":"Available operating systems (AWS only)","items":{"type":"string"}},"tenancy":{"type":"array","description":"Available tenancy types (AWS only)","items":{"type":"string"}}},"additionalProperties":false}}}}
```

## The ExchangePurchase object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ExchangePurchase":{"type":"object","properties":{"account_id":{"type":"string","description":"Target cloud account/subscription for the purchase.","nullable":true},"contract_term":{"description":"User-facing purchase commitment term. For leased/guaranteed purchases this is the lease lock-in term; for native purchases it is the offer duration.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease menu item attached to the purchase side, or null for native purchases.","nullable":true},"quantity":{"type":"integer","description":"Quantity of the Azure reservation to purchase."},"offer":{"description":"Azure reservation offer being purchased.","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"commitment_upfront_cost":{"type":"number","description":"One-time upfront dollars required at signing for the purchase side. NOT a monthly rate."},"commitment_financials_monthly_rate":{"description":"Purchase-side plan line item economics as 730-hour monthly rates.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","offer","quantity"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The ExchangeReturn object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ExchangeReturn":{"type":"object","properties":{"commitment":{"description":"Azure commitment proposed to return in the exchange.","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"quantity":{"type":"integer","description":"Quantity of this commitment proposed for return."},"remaining_lifetime_commitment":{"type":"number","description":"Remaining Azure commitment value returned for this commitment quantity. This is lifetime exchange value, not a monthly rate."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitment over the DailyUtilization period (0-1)."},"underutilized_commitment_cost":{"type":"number","description":"Estimated underutilized commitment cost over the DailyUtilization period. This is a period total, not a monthly rate."},"utilization_days":{"type":"integer","description":"Number of DailyUtilization days behind the utilization fields."},"reservation_resource_id":{"type":"string","description":"Azure reservation resource ID required by Azure exchange APIs."},"commitment_financials_monthly_rate":{"description":"Returned commitment economics as a 730-hour monthly rate for the selected integer return quantity. Cost comes from DailyUtilization commitment cost for the response period, scaled to the returned quantity. Savings are computed after assigning as much utilization as possible to the quantity that remains committed, so returned fully-utilized quantities can have positive savings and underutilized quantities have negative savings. Archera premium and rebate are excluded from exchange recommendations and are not included in net savings.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment","commitment_financials_monthly_rate","quantity","remaining_lifetime_commitment","reservation_resource_id","underutilized_commitment_cost","utilization","utilization_days"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The ExchangeReturnedCommitmentDailyUtilization object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ExchangeReturnedCommitmentDailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"DailyUtilization date."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitments for this date (0-1), dollar weighted by each return's commitment cost."}},"required":["date","utilization"],"additionalProperties":false}}}}
```

## The ExchangeRecommendationDelta object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ExchangeRecommendationDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Purchase monthly net savings minus returned commitments' monthly net savings. Positive means the exchange purchase saves more per 730-hour month."},"monthly_commitment_cost":{"type":"number","description":"Purchase monthly commitment cost minus returned commitments' monthly commitment cost. Positive means more monthly commitment spend."},"purchase_upfront_cost":{"type":"number","description":"Purchase-side one-time upfront cost only. Not netted against returned commitments because returned financials are monthly-rate utilization actuals and have no upfront component. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","purchase_upfront_cost"],"additionalProperties":false}}}}
```

## The ExchangeRecommendation object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ExchangeRecommendation":{"type":"object","properties":{"purchase_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value of the purchase side."},"returned_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value returned by the exchange."},"additional_lifetime_commitment":{"type":"number","description":"Purchase lifetime commitment minus returned lifetime commitment. Azure exchange policy requires this to be non-negative."},"purchase":{"$ref":"#/components/schemas/ExchangePurchase"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeReturn"}},"purchase_commitment_financials_monthly_rate":{"description":"Purchase-side monthly-rate financials.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"returned_commitment_financials_monthly_rate":{"description":"Returned commitments' rolled-up monthly-rate financials for the selected integer return quantities. Cost comes from DailyUtilization commitment cost, and savings are computed after assigning as much utilization as possible to the quantity that remains committed. Rebate and Archera premium are excluded from exchange recommendations and are not included in net savings.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"returned_commitment_daily_utilizations":{"type":"array","description":"Daily whole-commitment utilization for the returned commitments, dollar weighted by each return's commitment cost. Use this for exchange-level utilization charts.","items":{"$ref":"#/components/schemas/ExchangeReturnedCommitmentDailyUtilization"}},"reason":{"type":"string","description":"Short human-readable reason this exchange was recommended, based on how the exchanger generated it.","nullable":true},"delta_vs_returned":{"description":"Purchase-side economics compared with returned-commitment economics. Monthly fields are purchase-side minus returned-side; purchase_upfront_cost is purchase-side one-time upfront only and is not netted. Purchase financials come from plan-amortized line item financials; returned financials come from DailyUtilization cost and covered usage for the selected integer return quantities, normalized to 730-hour monthly rates.","allOf":[{"$ref":"#/components/schemas/ExchangeRecommendationDelta"}]}},"required":["additional_lifetime_commitment","delta_vs_returned","purchase","purchase_commitment_financials_monthly_rate","purchase_lifetime_commitment","returned_commitment_daily_utilizations","returned_commitment_financials_monthly_rate","returned_lifetime_commitment","returns"],"additionalProperties":false},"ExchangePurchase":{"type":"object","properties":{"account_id":{"type":"string","description":"Target cloud account/subscription for the purchase.","nullable":true},"contract_term":{"description":"User-facing purchase commitment term. For leased/guaranteed purchases this is the lease lock-in term; for native purchases it is the offer duration.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease menu item attached to the purchase side, or null for native purchases.","nullable":true},"quantity":{"type":"integer","description":"Quantity of the Azure reservation to purchase."},"offer":{"description":"Azure reservation offer being purchased.","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"commitment_upfront_cost":{"type":"number","description":"One-time upfront dollars required at signing for the purchase side. NOT a monthly rate."},"commitment_financials_monthly_rate":{"description":"Purchase-side plan line item economics as 730-hour monthly rates.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","offer","quantity"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"ExchangeReturn":{"type":"object","properties":{"commitment":{"description":"Azure commitment proposed to return in the exchange.","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"quantity":{"type":"integer","description":"Quantity of this commitment proposed for return."},"remaining_lifetime_commitment":{"type":"number","description":"Remaining Azure commitment value returned for this commitment quantity. This is lifetime exchange value, not a monthly rate."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitment over the DailyUtilization period (0-1)."},"underutilized_commitment_cost":{"type":"number","description":"Estimated underutilized commitment cost over the DailyUtilization period. This is a period total, not a monthly rate."},"utilization_days":{"type":"integer","description":"Number of DailyUtilization days behind the utilization fields."},"reservation_resource_id":{"type":"string","description":"Azure reservation resource ID required by Azure exchange APIs."},"commitment_financials_monthly_rate":{"description":"Returned commitment economics as a 730-hour monthly rate for the selected integer return quantity. Cost comes from DailyUtilization commitment cost for the response period, scaled to the returned quantity. Savings are computed after assigning as much utilization as possible to the quantity that remains committed, so returned fully-utilized quantities can have positive savings and underutilized quantities have negative savings. Archera premium and rebate are excluded from exchange recommendations and are not included in net savings.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment","commitment_financials_monthly_rate","quantity","remaining_lifetime_commitment","reservation_resource_id","underutilized_commitment_cost","utilization","utilization_days"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"ExchangeReturnedCommitmentDailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"DailyUtilization date."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitments for this date (0-1), dollar weighted by each return's commitment cost."}},"required":["date","utilization"],"additionalProperties":false},"ExchangeRecommendationDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Purchase monthly net savings minus returned commitments' monthly net savings. Positive means the exchange purchase saves more per 730-hour month."},"monthly_commitment_cost":{"type":"number","description":"Purchase monthly commitment cost minus returned commitments' monthly commitment cost. Positive means more monthly commitment spend."},"purchase_upfront_cost":{"type":"number","description":"Purchase-side one-time upfront cost only. Not netted against returned commitments because returned financials are monthly-rate utilization actuals and have no upfront component. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","purchase_upfront_cost"],"additionalProperties":false}}}}
```

## The ExchangeRecommendationsResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ExchangeRecommendationsResponse":{"type":"object","properties":{"current_utilization_lookback_days":{"type":"integer","description":"Number of trailing days of DailyUtilization used for returned-commitment utilization and financials."},"data":{"type":"array","description":"Azure exchange recommendations.","items":{"$ref":"#/components/schemas/ExchangeRecommendation"}}},"required":["current_utilization_lookback_days","data"],"additionalProperties":false},"ExchangeRecommendation":{"type":"object","properties":{"purchase_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value of the purchase side."},"returned_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value returned by the exchange."},"additional_lifetime_commitment":{"type":"number","description":"Purchase lifetime commitment minus returned lifetime commitment. Azure exchange policy requires this to be non-negative."},"purchase":{"$ref":"#/components/schemas/ExchangePurchase"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeReturn"}},"purchase_commitment_financials_monthly_rate":{"description":"Purchase-side monthly-rate financials.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"returned_commitment_financials_monthly_rate":{"description":"Returned commitments' rolled-up monthly-rate financials for the selected integer return quantities. Cost comes from DailyUtilization commitment cost, and savings are computed after assigning as much utilization as possible to the quantity that remains committed. Rebate and Archera premium are excluded from exchange recommendations and are not included in net savings.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"returned_commitment_daily_utilizations":{"type":"array","description":"Daily whole-commitment utilization for the returned commitments, dollar weighted by each return's commitment cost. Use this for exchange-level utilization charts.","items":{"$ref":"#/components/schemas/ExchangeReturnedCommitmentDailyUtilization"}},"reason":{"type":"string","description":"Short human-readable reason this exchange was recommended, based on how the exchanger generated it.","nullable":true},"delta_vs_returned":{"description":"Purchase-side economics compared with returned-commitment economics. Monthly fields are purchase-side minus returned-side; purchase_upfront_cost is purchase-side one-time upfront only and is not netted. Purchase financials come from plan-amortized line item financials; returned financials come from DailyUtilization cost and covered usage for the selected integer return quantities, normalized to 730-hour monthly rates.","allOf":[{"$ref":"#/components/schemas/ExchangeRecommendationDelta"}]}},"required":["additional_lifetime_commitment","delta_vs_returned","purchase","purchase_commitment_financials_monthly_rate","purchase_lifetime_commitment","returned_commitment_daily_utilizations","returned_commitment_financials_monthly_rate","returned_lifetime_commitment","returns"],"additionalProperties":false},"ExchangePurchase":{"type":"object","properties":{"account_id":{"type":"string","description":"Target cloud account/subscription for the purchase.","nullable":true},"contract_term":{"description":"User-facing purchase commitment term. For leased/guaranteed purchases this is the lease lock-in term; for native purchases it is the offer duration.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease menu item attached to the purchase side, or null for native purchases.","nullable":true},"quantity":{"type":"integer","description":"Quantity of the Azure reservation to purchase."},"offer":{"description":"Azure reservation offer being purchased.","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"commitment_upfront_cost":{"type":"number","description":"One-time upfront dollars required at signing for the purchase side. NOT a monthly rate."},"commitment_financials_monthly_rate":{"description":"Purchase-side plan line item economics as 730-hour monthly rates.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","offer","quantity"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"ExchangeReturn":{"type":"object","properties":{"commitment":{"description":"Azure commitment proposed to return in the exchange.","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"quantity":{"type":"integer","description":"Quantity of this commitment proposed for return."},"remaining_lifetime_commitment":{"type":"number","description":"Remaining Azure commitment value returned for this commitment quantity. This is lifetime exchange value, not a monthly rate."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitment over the DailyUtilization period (0-1)."},"underutilized_commitment_cost":{"type":"number","description":"Estimated underutilized commitment cost over the DailyUtilization period. This is a period total, not a monthly rate."},"utilization_days":{"type":"integer","description":"Number of DailyUtilization days behind the utilization fields."},"reservation_resource_id":{"type":"string","description":"Azure reservation resource ID required by Azure exchange APIs."},"commitment_financials_monthly_rate":{"description":"Returned commitment economics as a 730-hour monthly rate for the selected integer return quantity. Cost comes from DailyUtilization commitment cost for the response period, scaled to the returned quantity. Savings are computed after assigning as much utilization as possible to the quantity that remains committed, so returned fully-utilized quantities can have positive savings and underutilized quantities have negative savings. Archera premium and rebate are excluded from exchange recommendations and are not included in net savings.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["commitment","commitment_financials_monthly_rate","quantity","remaining_lifetime_commitment","reservation_resource_id","underutilized_commitment_cost","utilization","utilization_days"],"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"guaranteed_display_name":{"type":"string","description":"Commitment name when held as an Archera Guaranteed Commitment"},"type":{"type":"string","description":"Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')"},"status":{"description":"Commitment status (e.g. 'active', 'expired', 'queued')","type":"string","enum":["active","locked","new","reselling","unlocked","unknown","cancelled","expired","recently_expired","resold","removed"]},"is_active":{"type":"boolean","description":"Whether the commitment is currently active"},"is_archera_guaranteed":{"type":"boolean","description":"Whether this is an Archera Guaranteed Commitment"},"account_id":{"type":"string","description":"Cloud account ID this commitment is in","nullable":true},"billing_account_id":{"type":"string","description":"Billing/management account ID","nullable":true},"start_date":{"type":"string","format":"date-time","description":"When the commitment started","nullable":true},"end_date":{"type":"string","format":"date-time","description":"When the commitment expires","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds","nullable":true},"guarantee_start":{"type":"string","format":"date-time","description":"When the Archera guarantee period started","nullable":true},"guarantee_lockin_date":{"type":"string","format":"date-time","description":"When the Archera guarantee lock-in period ends","nullable":true},"guarantee_method":{"readOnly":true,"description":"How the Archera guarantee is delivered. 'rebate': Archera rebates the cost of the unused commitment directly to the user (as cash or credit toward Archera premiums). 'release': Archera takes over the commitment along with remaining payment obligations. Null for non-guaranteed commitments."},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge')","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5')","nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true},"instance_count":{"type":"integer","description":"Number of instances covered","nullable":true},"contract_term":{"description":"Contract term (e.g. 'thirty_day_gris', 'one_year')","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true}},"required":["id","provider"],"additionalProperties":false},"ExchangeReturnedCommitmentDailyUtilization":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"DailyUtilization date."},"utilization":{"type":"number","description":"Whole-commitment utilization of the returned commitments for this date (0-1), dollar weighted by each return's commitment cost."}},"required":["date","utilization"],"additionalProperties":false},"ExchangeRecommendationDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Purchase monthly net savings minus returned commitments' monthly net savings. Positive means the exchange purchase saves more per 730-hour month."},"monthly_commitment_cost":{"type":"number","description":"Purchase monthly commitment cost minus returned commitments' monthly commitment cost. Positive means more monthly commitment spend."},"purchase_upfront_cost":{"type":"number","description":"Purchase-side one-time upfront cost only. Not netted against returned commitments because returned financials are monthly-rate utilization actuals and have no upfront component. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","purchase_upfront_cost"],"additionalProperties":false}}}}
```

## The ApplyExchangePurchase object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ApplyExchangePurchase":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Azure reservation offer ID to purchase."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this offer to purchase."}},"required":["offer_id","quantity"],"additionalProperties":false}}}}
```

## The ApplyExchangeReturn object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ApplyExchangeReturn":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Existing Azure commitment ID to return."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this commitment to return."}},"required":["commitment_id","quantity"],"additionalProperties":false}}}}
```

## The ApplyExchangeRecommendationsArgs object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ApplyExchangeRecommendationsArgs":{"type":"object","properties":{"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"purchases":{"type":"array","minItems":1,"description":"Explicit purchase-side line items for one exchange recommendation.","items":{"$ref":"#/components/schemas/ApplyExchangePurchase"}},"returns":{"type":"array","minItems":1,"description":"Explicit return-side line items for one exchange recommendation.","items":{"$ref":"#/components/schemas/ApplyExchangeReturn"}}},"required":["provider","purchases","returns"],"additionalProperties":false},"ApplyExchangePurchase":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Azure reservation offer ID to purchase."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this offer to purchase."}},"required":["offer_id","quantity"],"additionalProperties":false},"ApplyExchangeReturn":{"type":"object","properties":{"commitment_id":{"type":"string","format":"uuid","description":"Existing Azure commitment ID to return."},"quantity":{"type":"integer","minimum":1,"description":"Quantity of this commitment to return."}},"required":["commitment_id","quantity"],"additionalProperties":false}}}}
```

## The ApplyExchangeRecommendationsResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ApplyExchangeRecommendationsResponse":{"type":"object","properties":{"status":{"type":"string","description":"Application status for the exchange recommendations."},"recommendation_count":{"type":"integer","description":"Number of exchange recommendations applied."}},"required":["recommendation_count","status"],"additionalProperties":false}}}}
```

## The Integration object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"Integration":{"type":"object","properties":{"id":{"type":"string","description":"Integration identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Integration name","nullable":true},"provider_organization_id":{"type":"string","description":"Cloud-provider organization/tenant identifier (AWS Organizations ID, Azure tenant ID, GCP organization ID).","nullable":true},"active":{"type":"boolean","description":"Whether this integration has active credentials"},"currency":{"type":"string","description":"Billing currency (e.g. 'USD')","nullable":true},"data_available_since":{"type":"string","format":"date-time","description":"Earliest date cost data is available from this integration","nullable":true},"data_available_until":{"type":"string","format":"date-time","description":"Latest date cost data is available from this integration","nullable":true}},"additionalProperties":false}}}}
```

## The IntegrationDetail object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"IntegrationDetail":{"type":"object","properties":{"id":{"type":"string","description":"Integration identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"name":{"type":"string","description":"Integration name","nullable":true},"provider_organization_id":{"type":"string","description":"Cloud-provider organization/tenant identifier (AWS Organizations ID, Azure tenant ID, GCP organization ID).","nullable":true},"active":{"type":"boolean","description":"Whether this integration has active credentials"},"currency":{"type":"string","description":"Billing currency (e.g. 'USD')","nullable":true},"data_available_since":{"type":"string","format":"date-time","description":"Earliest date cost data is available from this integration","nullable":true},"data_available_until":{"type":"string","format":"date-time","description":"Latest date cost data is available from this integration","nullable":true},"accounts":{"readOnly":true,"description":"Cloud accounts associated with this integration"}},"additionalProperties":false}}}}
```

## The ResourceSKUWithMetrics object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ResourceSKUWithMetrics":{"type":"object","properties":{"id":{"type":"string","description":"Composite ResourceSKU id — `<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`. Pass directly to `/resources/skus/<id>` for detail; do not parse it client-side."},"resource_id":{"type":"string","format":"uuid","description":"Underlying Resource id. Stable across SKU/time variants of the same resource — multiple ResourceSKU rows can share a `resource_id` when the same resource ran with different SKUs over its lifetime."},"catalog_sku_id":{"type":"string","format":"uuid","description":"Join key into `/catalog/skus/<id>` for the public SKU record."},"catalog_sku_org_id":{"type":"string","description":"Org id that owns the catalog SKU — public-catalog SKUs use the public org id; custom-priced SKUs use the customer's org id."},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"provider_resource_id":{"type":"string","description":"Provider's id for the resource (AWS ARN, Azure resource ID, GCP resource name). This is the canonical identifier the user sees in the cloud console."},"provider_sku_id":{"type":"string","description":"Provider's own SKU identifier","nullable":true},"name":{"type":"string","description":"Resource name (Resource.name) — the user-applied label, e.g. 'prod-db-1'. Distinct from `sku_name`, which is the catalog SKU's display name.","nullable":true},"sku_name":{"type":"string","description":"Catalog SKU display name (e.g. 'Amazon EC2 Instance', 'Amazon Aurora PostgreSQL Cluster'). Useful as a fallback label when `instance_type_family` and `usage_type` are both null. Distinct from `name` (the resource's user-applied label).","nullable":true},"integration_id":{"type":"string","description":"Integration this resource belongs to"},"billing_account_id":{"type":"string","description":"Provider billing/management account id","nullable":true},"sub_account_id":{"type":"string","description":"Provider account id that owns/created the resource","nullable":true},"resource_group":{"type":"string","nullable":true},"is_spot":{"type":"boolean","nullable":true},"availability_zone":{"type":"string","nullable":true},"service":{"type":"string","description":"Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')","nullable":true},"provider_service":{"type":"string","description":"Provider service code (e.g. 'AmazonEC2')","nullable":true},"family":{"type":"string","description":"Product family (e.g. 'Compute Instance')","nullable":true},"region_code":{"type":"string","description":"Region code (e.g. 'us-east-1')","nullable":true},"full_region_name":{"type":"string","description":"Full region name (e.g. 'US East (N. Virginia)')","nullable":true},"instance_type":{"type":"string","nullable":true},"instance_type_family":{"type":"string","nullable":true},"usage_type":{"type":"string","description":"Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items.","nullable":true},"operation":{"type":"string","description":"Provider billing operation code (e.g. 'RunInstances:0002')","nullable":true},"operating_system":{"type":"string","nullable":true},"tenancy":{"type":"string","nullable":true},"database_engine":{"type":"string","nullable":true},"database_edition":{"type":"string","nullable":true},"cache_engine":{"type":"string","nullable":true},"is_multi_az":{"type":"boolean","nullable":true},"is_current_generation":{"type":"boolean","nullable":true},"license_model":{"type":"string","nullable":true},"pre_installed_sw":{"type":"string","nullable":true},"processor_architecture":{"type":"string","nullable":true},"is_reservable":{"type":"boolean","description":"Whether the SKU this resource is running has at least one reserved-term offering. Reservability is a property of the SKU, not the resource.","nullable":true},"is_byol":{"type":"boolean","description":"Whether the SKU is a Bring-Your-Own-License variant. Currently set for AWS RDS BYOL only; false elsewhere.","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the SKU is eligible for instance-size flexibility under reserved offerings (provider+service-specific rules — see `is_flexible` on the ResourceSKU model).","nullable":true},"is_serverless":{"type":"boolean","description":"Whether the SKU represents serverless usage.","nullable":true},"vcpu":{"type":"number","nullable":true},"memory":{"type":"number","description":"Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.","nullable":true},"ondemand_usage_unit":{"type":"string","nullable":true},"ondemand_usage_price":{"type":"number","description":"On-demand unit price in `price_currency`. List price from the catalog — this is NOT the user's actual spend for this resource (see ResourceSKUWithMetricsSchema's `total_cost` or /cost-explorer for that).","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_start":{"type":"string","format":"date-time","description":"Start of the period during which the resource was observed running this SKU. A resource that switched SKUs (e.g. instance-type resize) will have multiple ResourceSKU rows with disjoint `[usage_start, usage_end]` windows."},"usage_end":{"type":"string","format":"date-time","description":"End of the period during which the resource was observed running this SKU. Within ~2 days of now generally indicates the resource is currently active with this SKU."},"tags":{"type":"object","description":"Merged provider + user tags (user tags take precedence). Empty when the resource has no tags. Use the `untagged` filter to find resources with no tags at all.","additionalProperties":{"type":"string"},"nullable":true},"total_cost":{"type":"number","description":"Trailing-30-day total spend on this resource — what the user actually paid, summing the on-demand, spot, and commitment-covered portions. Reflects actuals already incurred under existing commitments, NOT a projection. Zero for resources not active in the last month.","nullable":true},"ondemand_cost":{"type":"number","description":"Trailing-30-day on-demand-priced portion of `total_cost` — i.e. spend that wasn't covered by a commitment or run as spot. NOT the counterfactual 'what it would have cost at on-demand prices' (that's `if_all_ondemand_cost`).","nullable":true},"gross_savings":{"type":"number","description":"Trailing-30-day savings already realized on this resource vs the on-demand baseline (`if_all_ondemand_cost - total_cost`). Actuals from existing commitments — NOT a projection of what a candidate plan would save. Per-row clamped at zero, so summing this across resources never goes negative. Archera premium is NOT subtracted on this endpoint (premium isn't attributed per resource here); for portfolio-level net savings see /commitments/metrics.","nullable":true},"if_all_ondemand_cost":{"readOnly":true,"description":"Trailing-30-day on-demand counterfactual — what `total_cost` would be if every hour of usage ran at on-demand prices. Equals `total_cost + gross_savings`. Headline baseline for 'how much is this commitment-covered resource saving me'."},"coverage":{"type":"number","description":"Trailing-30-day spend-based fraction of this resource's usage covered by ALL existing commitments (0-1). At this single-SKU granularity, the usage-unit and spend ratios are equivalent. Actuals — the BEFORE picture relative to any candidate plan. When nested inside a commitment plan's covered-resources response, this is distinct from per-match `projected_coverage` (the AFTER picture for that plan).","nullable":true},"uptime":{"type":"number","description":"Trailing-30-day fraction of time the resource was running (0-1). Null for non-running SKU types (storage, data transfer, etc.). Useful for rightsizing flags — low uptime on a large instance is a candidate for downsizing or termination.","nullable":true}},"additionalProperties":false}}}}
```

## The CoveringCommitmentEntry object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CoveringCommitmentEntry":{"type":"object","properties":{"commitment_id":{"type":"string","description":"Archera id of a commitment that covers this resource's usage."},"covered_usage":{"type":"number","description":"Sum of usage_amount_normalized this commitment covered on this resource over the period."},"share_pct":{"type":"number","description":"This commitment's share of the resource's total covered usage in the period, in [0, 1]. Across all rows this sums to 1."}},"additionalProperties":false}}}}
```

## The ResourceSKUDetail object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"ResourceSKUDetail":{"type":"object","properties":{"id":{"type":"string","description":"Composite ResourceSKU id — `<resource_id>|<catalog_sku_org_id>|<catalog_sku_id>`. Pass directly to `/resources/skus/<id>` for detail; do not parse it client-side."},"resource_id":{"type":"string","format":"uuid","description":"Underlying Resource id. Stable across SKU/time variants of the same resource — multiple ResourceSKU rows can share a `resource_id` when the same resource ran with different SKUs over its lifetime."},"catalog_sku_id":{"type":"string","format":"uuid","description":"Join key into `/catalog/skus/<id>` for the public SKU record."},"catalog_sku_org_id":{"type":"string","description":"Org id that owns the catalog SKU — public-catalog SKUs use the public org id; custom-priced SKUs use the customer's org id."},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"provider_resource_id":{"type":"string","description":"Provider's id for the resource (AWS ARN, Azure resource ID, GCP resource name). This is the canonical identifier the user sees in the cloud console."},"provider_sku_id":{"type":"string","description":"Provider's own SKU identifier","nullable":true},"name":{"type":"string","description":"Resource name (Resource.name) — the user-applied label, e.g. 'prod-db-1'. Distinct from `sku_name`, which is the catalog SKU's display name.","nullable":true},"sku_name":{"type":"string","description":"Catalog SKU display name (e.g. 'Amazon EC2 Instance', 'Amazon Aurora PostgreSQL Cluster'). Useful as a fallback label when `instance_type_family` and `usage_type` are both null. Distinct from `name` (the resource's user-applied label).","nullable":true},"integration_id":{"type":"string","description":"Integration this resource belongs to"},"billing_account_id":{"type":"string","description":"Provider billing/management account id","nullable":true},"sub_account_id":{"type":"string","description":"Provider account id that owns/created the resource","nullable":true},"resource_group":{"type":"string","nullable":true},"is_spot":{"type":"boolean","nullable":true},"availability_zone":{"type":"string","nullable":true},"service":{"type":"string","description":"Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')","nullable":true},"provider_service":{"type":"string","description":"Provider service code (e.g. 'AmazonEC2')","nullable":true},"family":{"type":"string","description":"Product family (e.g. 'Compute Instance')","nullable":true},"region_code":{"type":"string","description":"Region code (e.g. 'us-east-1')","nullable":true},"full_region_name":{"type":"string","description":"Full region name (e.g. 'US East (N. Virginia)')","nullable":true},"instance_type":{"type":"string","nullable":true},"instance_type_family":{"type":"string","nullable":true},"usage_type":{"type":"string","description":"Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items.","nullable":true},"operation":{"type":"string","description":"Provider billing operation code (e.g. 'RunInstances:0002')","nullable":true},"operating_system":{"type":"string","nullable":true},"tenancy":{"type":"string","nullable":true},"database_engine":{"type":"string","nullable":true},"database_edition":{"type":"string","nullable":true},"cache_engine":{"type":"string","nullable":true},"is_multi_az":{"type":"boolean","nullable":true},"is_current_generation":{"type":"boolean","nullable":true},"license_model":{"type":"string","nullable":true},"pre_installed_sw":{"type":"string","nullable":true},"processor_architecture":{"type":"string","nullable":true},"is_reservable":{"type":"boolean","description":"Whether the SKU this resource is running has at least one reserved-term offering. Reservability is a property of the SKU, not the resource.","nullable":true},"is_byol":{"type":"boolean","description":"Whether the SKU is a Bring-Your-Own-License variant. Currently set for AWS RDS BYOL only; false elsewhere.","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the SKU is eligible for instance-size flexibility under reserved offerings (provider+service-specific rules — see `is_flexible` on the ResourceSKU model).","nullable":true},"is_serverless":{"type":"boolean","description":"Whether the SKU represents serverless usage.","nullable":true},"vcpu":{"type":"number","nullable":true},"memory":{"type":"number","description":"Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.","nullable":true},"ondemand_usage_unit":{"type":"string","nullable":true},"ondemand_usage_price":{"type":"number","description":"On-demand unit price in `price_currency`. List price from the catalog — this is NOT the user's actual spend for this resource (see ResourceSKUWithMetricsSchema's `total_cost` or /cost-explorer for that).","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_start":{"type":"string","format":"date-time","description":"Start of the period during which the resource was observed running this SKU. A resource that switched SKUs (e.g. instance-type resize) will have multiple ResourceSKU rows with disjoint `[usage_start, usage_end]` windows."},"usage_end":{"type":"string","format":"date-time","description":"End of the period during which the resource was observed running this SKU. Within ~2 days of now generally indicates the resource is currently active with this SKU."},"tags":{"type":"object","description":"Merged provider + user tags (user tags take precedence). Empty when the resource has no tags. Use the `untagged` filter to find resources with no tags at all.","additionalProperties":{"type":"string"},"nullable":true},"total_cost":{"type":"number","description":"Trailing-30-day total spend on this resource — what the user actually paid, summing the on-demand, spot, and commitment-covered portions. Reflects actuals already incurred under existing commitments, NOT a projection. Zero for resources not active in the last month.","nullable":true},"ondemand_cost":{"type":"number","description":"Trailing-30-day on-demand-priced portion of `total_cost` — i.e. spend that wasn't covered by a commitment or run as spot. NOT the counterfactual 'what it would have cost at on-demand prices' (that's `if_all_ondemand_cost`).","nullable":true},"gross_savings":{"type":"number","description":"Trailing-30-day savings already realized on this resource vs the on-demand baseline (`if_all_ondemand_cost - total_cost`). Actuals from existing commitments — NOT a projection of what a candidate plan would save. Per-row clamped at zero, so summing this across resources never goes negative. Archera premium is NOT subtracted on this endpoint (premium isn't attributed per resource here); for portfolio-level net savings see /commitments/metrics.","nullable":true},"if_all_ondemand_cost":{"readOnly":true,"description":"Trailing-30-day on-demand counterfactual — what `total_cost` would be if every hour of usage ran at on-demand prices. Equals `total_cost + gross_savings`. Headline baseline for 'how much is this commitment-covered resource saving me'."},"coverage":{"type":"number","description":"Trailing-30-day spend-based fraction of this resource's usage covered by ALL existing commitments (0-1). At this single-SKU granularity, the usage-unit and spend ratios are equivalent. Actuals — the BEFORE picture relative to any candidate plan. When nested inside a commitment plan's covered-resources response, this is distinct from per-match `projected_coverage` (the AFTER picture for that plan).","nullable":true},"uptime":{"type":"number","description":"Trailing-30-day fraction of time the resource was running (0-1). Null for non-running SKU types (storage, data transfer, etc.). Useful for rightsizing flags — low uptime on a large instance is a candidate for downsizing or termination.","nullable":true},"parent_resource_id":{"type":"string","format":"uuid","description":"Parent Resource id (e.g. the spot fleet / autoscaling group / RDS cluster that owns this resource). Sparse — only populated when the cloud provider exposes a parent relationship. Use this to traverse resource hierarchies.","nullable":true},"description":{"type":"string","nullable":true},"location_type":{"type":"string","nullable":true},"physical_processor":{"type":"string","nullable":true},"clock_speed":{"type":"string","nullable":true},"processor_features":{"type":"string","nullable":true},"network_performance":{"type":"string","nullable":true},"storage":{"type":"string","nullable":true},"dedicated_ebs_throughput":{"type":"string","nullable":true},"io":{"type":"string","nullable":true},"tax_type":{"type":"string","nullable":true},"has_ondemand_terms":{"type":"boolean","nullable":true},"normalization_size_factor":{"type":"number","description":"AWS instance-size flexibility unit. Used internally to size convertible RIs across the family; not generally user-facing.","nullable":true},"publication_date":{"type":"string","format":"date-time","description":"When the catalog SKU version was published by the provider.","nullable":true},"end_date":{"type":"string","format":"date-time","description":"Date after which the catalog SKU is no longer available.","nullable":true},"attributes":{"description":"Raw provider-specific attribute blob from the catalog SKU — usually a JSON object, but can be any JSON value (string, list, etc.) since the underlying column is a Snowflake VARIANT. May overlap with the structured fields above; prefer the structured fields when they're populated.","nullable":true},"provider_tags":{"type":"object","description":"Tags assigned by the cloud provider, before user overrides are merged.","additionalProperties":{"type":"string"}},"user_tags":{"type":"object","description":"Tags applied via the Archera UI/API on top of the provider tags.","additionalProperties":{"type":"string"}},"covering_commitments":{"type":"array","description":"Per-commitment breakdown of CUDs covering this resource's usage over the requested period. Populated only when the request includes `expand=covering_commitments`; null otherwise to keep typical detail calls from paying the aggregation scan.","items":{"$ref":"#/components/schemas/CoveringCommitmentEntry"},"nullable":true}},"additionalProperties":false},"CoveringCommitmentEntry":{"type":"object","properties":{"commitment_id":{"type":"string","description":"Archera id of a commitment that covers this resource's usage."},"covered_usage":{"type":"number","description":"Sum of usage_amount_normalized this commitment covered on this resource over the period."},"share_pct":{"type":"number","description":"This commitment's share of the resource's total covered usage in the period, in [0, 1]. Across all rows this sums to 1."}},"additionalProperties":false}}}}
```

## The CatalogSKU object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CatalogSKU":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Catalog SKU id"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"provider_sku_id":{"type":"string","description":"Provider's own SKU identifier"},"name":{"type":"string","nullable":true},"family":{"type":"string","description":"Product family (e.g. 'Compute Instance')","nullable":true},"service":{"type":"string","description":"Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')","nullable":true},"provider_service":{"type":"string","description":"Provider service code (e.g. 'AmazonEC2')","nullable":true},"region_code":{"type":"string","description":"Region code (e.g. 'us-east-1')","nullable":true},"full_region_name":{"type":"string","description":"Full region name (e.g. 'US East (N. Virginia)')","nullable":true},"instance_type":{"type":"string","nullable":true},"instance_type_family":{"type":"string","nullable":true},"usage_type":{"type":"string","description":"Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items — useful for crossing between catalog and cost data.","nullable":true},"operation":{"type":"string","description":"Provider billing operation code (e.g. 'RunInstances:0002'). Lets the agent spot at-a-glance whether a SKU is the plain default operation or a more specific variant within a usage_type.","nullable":true},"operating_system":{"type":"string","nullable":true},"tenancy":{"type":"string","nullable":true},"database_engine":{"type":"string","nullable":true},"database_edition":{"type":"string","nullable":true},"cache_engine":{"type":"string","nullable":true},"is_multi_az":{"type":"boolean","nullable":true},"is_current_generation":{"type":"boolean","nullable":true},"license_model":{"type":"string","nullable":true},"pre_installed_sw":{"type":"string","nullable":true},"processor_architecture":{"type":"string","description":"CPU architecture (e.g. 'x86_64', 'arm64')","nullable":true},"vcpu":{"type":"number","nullable":true},"memory":{"type":"number","description":"Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.","nullable":true},"is_reservable":{"type":"boolean","description":"Whether this SKU has at least one reserved-term offering"},"is_public":{"type":"boolean","description":"True for public-catalog SKUs (the standard provider catalog). False when this row is the requesting org's own custom-priced SKU (tied to a specific integration; drill into `catalog_sku_details` for the integration_id)."},"ondemand_usage_unit":{"type":"string","nullable":true},"ondemand_usage_price":{"type":"number","description":"On-demand unit price in price_currency","nullable":true},"price_currency":{"type":"string","nullable":true}},"additionalProperties":false}}}}
```

## The PriceDimension object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"PriceDimension":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"description":{"type":"string","nullable":true},"usage_unit":{"type":"string","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_unit_price":{"type":"number","nullable":true},"begin_range":{"type":"number","description":"Tier lower bound (in usage units)","nullable":true},"end_range":{"type":"number","description":"Tier upper bound (in usage units); null means infinite","nullable":true}},"additionalProperties":false}}}}
```

## The SKUTerms object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"SKUTerms":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"effective_date":{"type":"string","format":"date-time","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_unit":{"type":"string","nullable":true},"usage_unit_price":{"type":"number","nullable":true},"price_dimensions":{"type":"array","items":{"$ref":"#/components/schemas/PriceDimension"}}},"additionalProperties":false},"PriceDimension":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"description":{"type":"string","nullable":true},"usage_unit":{"type":"string","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_unit_price":{"type":"number","nullable":true},"begin_range":{"type":"number","description":"Tier lower bound (in usage units)","nullable":true},"end_range":{"type":"number","description":"Tier upper bound (in usage units); null means infinite","nullable":true}},"additionalProperties":false}}}}
```

## The CatalogSKUDetail object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CatalogSKUDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Catalog SKU id"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"provider_sku_id":{"type":"string","description":"Provider's own SKU identifier"},"name":{"type":"string","nullable":true},"family":{"type":"string","description":"Product family (e.g. 'Compute Instance')","nullable":true},"service":{"type":"string","description":"Full service name (e.g. 'Amazon Elastic Compute Cloud - Compute')","nullable":true},"provider_service":{"type":"string","description":"Provider service code (e.g. 'AmazonEC2')","nullable":true},"region_code":{"type":"string","description":"Region code (e.g. 'us-east-1')","nullable":true},"full_region_name":{"type":"string","description":"Full region name (e.g. 'US East (N. Virginia)')","nullable":true},"instance_type":{"type":"string","nullable":true},"instance_type_family":{"type":"string","nullable":true},"usage_type":{"type":"string","description":"Provider billing usage type (e.g. 'BoxUsage:m5.large'). The canonical join key against AWS Cost Explorer / billing line items — useful for crossing between catalog and cost data.","nullable":true},"operation":{"type":"string","description":"Provider billing operation code (e.g. 'RunInstances:0002'). Lets the agent spot at-a-glance whether a SKU is the plain default operation or a more specific variant within a usage_type.","nullable":true},"operating_system":{"type":"string","nullable":true},"tenancy":{"type":"string","nullable":true},"database_engine":{"type":"string","nullable":true},"database_edition":{"type":"string","nullable":true},"cache_engine":{"type":"string","nullable":true},"is_multi_az":{"type":"boolean","nullable":true},"is_current_generation":{"type":"boolean","nullable":true},"license_model":{"type":"string","nullable":true},"pre_installed_sw":{"type":"string","nullable":true},"processor_architecture":{"type":"string","description":"CPU architecture (e.g. 'x86_64', 'arm64')","nullable":true},"vcpu":{"type":"number","nullable":true},"memory":{"type":"number","description":"Memory in bytes (not GB). Divide by 2**30 for GiB / 1e9 for GB if presenting to the user.","nullable":true},"is_reservable":{"type":"boolean","description":"Whether this SKU has at least one reserved-term offering"},"is_public":{"type":"boolean","description":"True for public-catalog SKUs (the standard provider catalog). False when this row is the requesting org's own custom-priced SKU (tied to a specific integration; drill into `catalog_sku_details` for the integration_id)."},"ondemand_usage_unit":{"type":"string","nullable":true},"ondemand_usage_price":{"type":"number","description":"On-demand unit price in price_currency","nullable":true},"price_currency":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"location_type":{"type":"string","nullable":true},"availability_zone":{"type":"string","nullable":true},"physical_processor":{"type":"string","nullable":true},"clock_speed":{"type":"string","nullable":true},"processor_features":{"type":"string","nullable":true},"network_performance":{"type":"string","nullable":true},"storage":{"type":"string","nullable":true},"dedicated_ebs_throughput":{"type":"string","nullable":true},"io":{"type":"string","nullable":true},"tax_type":{"type":"string","nullable":true},"has_ondemand_terms":{"type":"boolean"},"normalization_size_factor":{"type":"number","description":"AWS instance-size flexibility unit. Used internally to size convertible RIs across the family; not generally user-facing.","nullable":true},"is_byol":{"type":"boolean","description":"Whether this SKU is a Bring-Your-Own-License variant. Derived from license_model."},"integration_id":{"type":"string","format":"uuid","description":"Integration this SKU's custom pricing is tied to. Null for public-catalog SKUs (the default scope of the list endpoint). Set when the SKU id resolves to a custom-priced SKU on the requesting org — direct-id detail lookups support both public and the org's own custom-priced SKUs.","nullable":true},"end_date":{"type":"string","format":"date-time","description":"Date after which this SKU is no longer available.","nullable":true},"publication_date":{"type":"string","format":"date-time","description":"When this SKU version was published by the provider.","nullable":true},"updated_at":{"type":"string","format":"date","description":"When this SKU was last refreshed in our catalog.","nullable":true},"attributes":{"type":"object","description":"Raw provider-specific attribute blob. May overlap with the structured fields above; prefer the structured fields when they're populated.","additionalProperties":{},"nullable":true},"ondemand_terms":{"anyOf":[{"type":"object","nullable":true},{"$ref":"#/components/schemas/SKUTerms"}]}},"additionalProperties":false},"SKUTerms":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"effective_date":{"type":"string","format":"date-time","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_unit":{"type":"string","nullable":true},"usage_unit_price":{"type":"number","nullable":true},"price_dimensions":{"type":"array","items":{"$ref":"#/components/schemas/PriceDimension"}}},"additionalProperties":false},"PriceDimension":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"description":{"type":"string","nullable":true},"usage_unit":{"type":"string","nullable":true},"price_currency":{"type":"string","nullable":true},"usage_unit_price":{"type":"number","nullable":true},"begin_range":{"type":"number","description":"Tier lower bound (in usage units)","nullable":true},"end_range":{"type":"number","description":"Tier upper bound (in usage units); null means infinite","nullable":true}},"additionalProperties":false}}}}
```

## The CatalogSKUTargetDelta object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CatalogSKUTargetDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Monthly net savings under this target's resolved candidate vs running on-demand. Equals `commitment_financials_monthly_rate.commitment_savings.net` when a candidate resolved; 0 when `actual_term_reason='no_alternative'` (no commitment, you stay on-demand)."},"monthly_commitment_cost":{"type":"number","description":"Monthly commitment cost under this target's resolved candidate. 0 when no alternative resolved."},"upfront_cost":{"type":"number","description":"One-time upfront dollars under this target's resolved candidate. 0 when no alternative resolved. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The CatalogSKUResolution object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CatalogSKUResolution":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid"},"actual_term":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"]}},"required":["actual_payment_option","actual_term","actual_term_reason","sku_id"],"additionalProperties":false}}}}
```

## The CatalogSKUHypotheticalTotal object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CatalogSKUHypotheticalTotal":{"type":"object","properties":{"contract_term":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"commitment_upfront_cost":{"type":"number"},"delta_vs_ondemand":{"$ref":"#/components/schemas/CatalogSKUTargetDelta"},"skus":{"type":"array","description":"Per-SKU resolution for this rollup. Surface fallback and no-alternative rows instead of implying every SKU matched the requested term.","items":{"$ref":"#/components/schemas/CatalogSKUResolution"}}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_ondemand","payment_option","skus"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CatalogSKUTargetDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Monthly net savings under this target's resolved candidate vs running on-demand. Equals `commitment_financials_monthly_rate.commitment_savings.net` when a candidate resolved; 0 when `actual_term_reason='no_alternative'` (no commitment, you stay on-demand)."},"monthly_commitment_cost":{"type":"number","description":"Monthly commitment cost under this target's resolved candidate. 0 when no alternative resolved."},"upfront_cost":{"type":"number","description":"One-time upfront dollars under this target's resolved candidate. 0 when no alternative resolved. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"CatalogSKUResolution":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid"},"actual_term":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"]}},"required":["actual_payment_option","actual_term","actual_term_reason","sku_id"],"additionalProperties":false}}}}
```

## The CatalogSKUOndemandBaseline object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CatalogSKUOndemandBaseline":{"type":"object","properties":{"monthly_cost":{"type":"number","description":"Average monthly on-demand cost for covered_quantity. Hourly rates are multiplied by 730; day, month, and year units are normalized to the same average-month basis."},"ondemand_usage_unit":{"type":"string","description":"Unit of measurement for on-demand usage (e.g. 'Hrs').","nullable":true},"ondemand_usage_price":{"type":"number","description":"Per-unit on-demand price in USD."}},"required":["monthly_cost","ondemand_usage_price"],"additionalProperties":false}}}}
```

## The CatalogSKUOfferComparisonEntry object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CatalogSKUOfferComparisonEntry":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Commitment offer id."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for a native (non-Archera) commitment.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Match the underlying offer.type to interpret."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. 'one_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). The real lock-in period, not the offer's raw duration.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Payment option (no_upfront / partial_upfront / all_upfront).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1)."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself; null if undefined.","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as line items / plans. `commitment_savings.net` is the headline savings vs running on-demand.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","discount_rate","lease_menu_item_id","offer","offer_id","payment_option","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false}}}}
```

## The CatalogSKUTarget object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CatalogSKUTarget":{"type":"object","properties":{"contract_term":{"description":"Requested contract term for this hypothetical.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Requested payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"actual_term":{"description":"The contract term that actually resolved. Equals `contract_term` when an exact match exists; otherwise the longest term shorter than the target with the same payment option. Null when no alternative exists for the requested (term, payment) pair.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the resolved candidate. Equals `payment_option` whenever a candidate resolved (resolution preserves payment option); null when no alternative.","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this target landed at `actual_term`. `exact_match` = the SKU offers exactly this (term, payment). `fallback_closest_shorter` = no exact match; resolved to the longest term shorter than target with the same payment option (GRI variant preferred when same duration). `no_alternative` = nothing qualifies; surfaced explicitly so the agent can flag to the user that this (term, payment) combination doesn't exist for the SKU."},"candidate":{"description":"The resolved (offer, lease) candidate, or null when `actual_term_reason='no_alternative'`. Same shape as entries in `candidates[]` — the agent can quote `discount_rate`, `breakeven_days`, etc. directly off this nested entry.","anyOf":[{"$ref":"#/components/schemas/CatalogSKUOfferComparisonEntry"},{"type":"object","nullable":true}]},"commitment_financials_monthly_rate":{"description":"Resolved candidate's 730-hour monthly-rate financials, lifted to the top level so the agent can read the same paths as on the line-item endpoint's `hypothetical_totals[i]`. All-zero when `actual_term_reason='no_alternative'`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Resolved candidate's one-time upfront cost. 0 when no alternative resolved. NOT a rate."},"delta_vs_ondemand":{"description":"Axis-by-axis difference vs the on-demand baseline. Analogous to `delta_vs_current` on the line-item endpoint, but the baseline is on-demand (zero commitment) so each field equals the resolved candidate's value directly.","allOf":[{"$ref":"#/components/schemas/CatalogSKUTargetDelta"}]}},"required":["actual_payment_option","actual_term","actual_term_reason","candidate","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_ondemand","payment_option"],"additionalProperties":false},"CatalogSKUOfferComparisonEntry":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Commitment offer id."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for a native (non-Archera) commitment.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Match the underlying offer.type to interpret."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. 'one_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). The real lock-in period, not the offer's raw duration.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Payment option (no_upfront / partial_upfront / all_upfront).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1)."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself; null if undefined.","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as line items / plans. `commitment_savings.net` is the headline savings vs running on-demand.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","discount_rate","lease_menu_item_id","offer","offer_id","payment_option","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CatalogSKUTargetDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Monthly net savings under this target's resolved candidate vs running on-demand. Equals `commitment_financials_monthly_rate.commitment_savings.net` when a candidate resolved; 0 when `actual_term_reason='no_alternative'` (no commitment, you stay on-demand)."},"monthly_commitment_cost":{"type":"number","description":"Monthly commitment cost under this target's resolved candidate. 0 when no alternative resolved."},"upfront_cost":{"type":"number","description":"One-time upfront dollars under this target's resolved candidate. 0 when no alternative resolved. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The CatalogSKUOfferComparisonRow object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CatalogSKUOfferComparisonRow":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid","description":"The CatalogSKU id compared."},"quantity":{"type":"integer","description":"Requested catalog quantity."},"covered_quantity":{"type":"number","description":"Catalog quantity covered after provider package-size and normalized-unit rounding. May exceed quantity when offers are sold in indivisible blocks."},"ondemand_baseline":{"description":"On-demand reference point. Compare against each candidate's `commitment_financials_monthly_rate.commitment_cost.total` to see the absolute savings, or read `discount_rate` for the relative figure.","allOf":[{"$ref":"#/components/schemas/CatalogSKUOndemandBaseline"}]},"candidates":{"type":"array","description":"All (offer, lease) pairs available for this SKU at the requested quantity, filtered to the requested contract_terms and payment_options. Ordered by descending discount_rate.","items":{"$ref":"#/components/schemas/CatalogSKUOfferComparisonEntry"}},"targets":{"type":"array","description":"One entry per requested (contract_term, payment_option) target — what the SKU resolves to under that hypothetical, with `actual_term_reason` explaining whether it was an exact match, a fallback to the closest shorter term, or no alternative. Mirrors the line-item endpoint's `hypothetical_totals` shape within this per-SKU response row. The headline 'should I do this' answer per target is `delta_vs_ondemand.monthly_net_savings`.","items":{"$ref":"#/components/schemas/CatalogSKUTarget"}}},"required":["candidates","covered_quantity","ondemand_baseline","quantity","sku_id","targets"],"additionalProperties":false},"CatalogSKUOndemandBaseline":{"type":"object","properties":{"monthly_cost":{"type":"number","description":"Average monthly on-demand cost for covered_quantity. Hourly rates are multiplied by 730; day, month, and year units are normalized to the same average-month basis."},"ondemand_usage_unit":{"type":"string","description":"Unit of measurement for on-demand usage (e.g. 'Hrs').","nullable":true},"ondemand_usage_price":{"type":"number","description":"Per-unit on-demand price in USD."}},"required":["monthly_cost","ondemand_usage_price"],"additionalProperties":false},"CatalogSKUOfferComparisonEntry":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Commitment offer id."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for a native (non-Archera) commitment.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Match the underlying offer.type to interpret."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. 'one_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). The real lock-in period, not the offer's raw duration.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Payment option (no_upfront / partial_upfront / all_upfront).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1)."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself; null if undefined.","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as line items / plans. `commitment_savings.net` is the headline savings vs running on-demand.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","discount_rate","lease_menu_item_id","offer","offer_id","payment_option","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CatalogSKUTarget":{"type":"object","properties":{"contract_term":{"description":"Requested contract term for this hypothetical.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Requested payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"actual_term":{"description":"The contract term that actually resolved. Equals `contract_term` when an exact match exists; otherwise the longest term shorter than the target with the same payment option. Null when no alternative exists for the requested (term, payment) pair.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the resolved candidate. Equals `payment_option` whenever a candidate resolved (resolution preserves payment option); null when no alternative.","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this target landed at `actual_term`. `exact_match` = the SKU offers exactly this (term, payment). `fallback_closest_shorter` = no exact match; resolved to the longest term shorter than target with the same payment option (GRI variant preferred when same duration). `no_alternative` = nothing qualifies; surfaced explicitly so the agent can flag to the user that this (term, payment) combination doesn't exist for the SKU."},"candidate":{"description":"The resolved (offer, lease) candidate, or null when `actual_term_reason='no_alternative'`. Same shape as entries in `candidates[]` — the agent can quote `discount_rate`, `breakeven_days`, etc. directly off this nested entry.","anyOf":[{"$ref":"#/components/schemas/CatalogSKUOfferComparisonEntry"},{"type":"object","nullable":true}]},"commitment_financials_monthly_rate":{"description":"Resolved candidate's 730-hour monthly-rate financials, lifted to the top level so the agent can read the same paths as on the line-item endpoint's `hypothetical_totals[i]`. All-zero when `actual_term_reason='no_alternative'`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Resolved candidate's one-time upfront cost. 0 when no alternative resolved. NOT a rate."},"delta_vs_ondemand":{"description":"Axis-by-axis difference vs the on-demand baseline. Analogous to `delta_vs_current` on the line-item endpoint, but the baseline is on-demand (zero commitment) so each field equals the resolved candidate's value directly.","allOf":[{"$ref":"#/components/schemas/CatalogSKUTargetDelta"}]}},"required":["actual_payment_option","actual_term","actual_term_reason","candidate","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_ondemand","payment_option"],"additionalProperties":false},"CatalogSKUTargetDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Monthly net savings under this target's resolved candidate vs running on-demand. Equals `commitment_financials_monthly_rate.commitment_savings.net` when a candidate resolved; 0 when `actual_term_reason='no_alternative'` (no commitment, you stay on-demand)."},"monthly_commitment_cost":{"type":"number","description":"Monthly commitment cost under this target's resolved candidate. 0 when no alternative resolved."},"upfront_cost":{"type":"number","description":"One-time upfront dollars under this target's resolved candidate. 0 when no alternative resolved. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false}}}}
```

## The SkippedCatalogSKU object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"SkippedCatalogSKU":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid"},"reason":{"type":"string"}},"required":["reason","sku_id"],"additionalProperties":false}}}}
```

## The CatalogSKUOfferComparisonResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CatalogSKUOfferComparisonResponse":{"type":"object","properties":{"ondemand_baseline_monthly_cost":{"type":"number","description":"Combined average monthly on-demand cost across matched SKUs at each row's covered_quantity, normalized for time-based billing units."},"hypothetical_totals":{"type":"array","items":{"$ref":"#/components/schemas/CatalogSKUHypotheticalTotal"}},"data":{"type":"array","description":"Per-SKU comparison detail in request order.","items":{"$ref":"#/components/schemas/CatalogSKUOfferComparisonRow"}},"skipped_skus":{"type":"array","description":"Requested SKUs that were missing, inaccessible, non-reservable, unpriced, unmatched, or could not be priced, and were excluded from data and totals.","items":{"$ref":"#/components/schemas/SkippedCatalogSKU"}}},"required":["data","hypothetical_totals","ondemand_baseline_monthly_cost","skipped_skus"],"additionalProperties":false},"CatalogSKUHypotheticalTotal":{"type":"object","properties":{"contract_term":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month"]},"payment_option":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"commitment_financials_monthly_rate":{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"commitment_upfront_cost":{"type":"number"},"delta_vs_ondemand":{"$ref":"#/components/schemas/CatalogSKUTargetDelta"},"skus":{"type":"array","description":"Per-SKU resolution for this rollup. Surface fallback and no-alternative rows instead of implying every SKU matched the requested term.","items":{"$ref":"#/components/schemas/CatalogSKUResolution"}}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_ondemand","payment_option","skus"],"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}},"additionalProperties":false},"CommitmentCost":{"type":"object","properties":{"total":{"type":"number","description":"Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'."},"breakdown":{"$ref":"#/components/schemas/CommitmentCostBreakdown"}},"additionalProperties":false},"CommitmentCostBreakdown":{"type":"object","properties":{"cloud_provider_cost":{"$ref":"#/components/schemas/CloudProviderCost"},"archera_premium":{"type":"number","description":"Archera premium — paid to Archera, equal to a portion of the savings Archera generates for this commitment (fee_rate * gross savings, only charged when gross > 0). Already included in commitment_cost.total (don't add on top). Because premium is only a fraction of gross, whenever archera_premium > 0 the commitment is net-positive after the fee. Native (non-Archera) commitments have premium = 0 and offer no such guarantee; an underutilized guaranteed commitment pre-lockin can also show net < 0 (the rebate that covers this kicks in post-lockin)."}},"additionalProperties":false},"CloudProviderCost":{"type":"object","properties":{"total":{"type":"number","description":"Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total."},"breakdown":{"description":"Optional. Additive payment-cadence decomposition of total (recurring + amortized_upfront). Present only when purchase-term structure is known (individual commitment or plan).","allOf":[{"$ref":"#/components/schemas/CloudProviderCostBreakdown"}]}},"additionalProperties":false},"CloudProviderCostBreakdown":{"type":"object","properties":{"recurring":{"type":"number","description":"Recurring monthly payment to the cloud provider."},"amortized_upfront":{"type":"number","description":"Monthly share of the upfront payment, amortized over the term."}},"additionalProperties":false},"CommitmentSavings_Exclude_Rebate":{"type":"object","properties":{"net":{"type":"number","description":"Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'."},"gross":{"type":"number","description":"Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total."}},"additionalProperties":false},"CatalogSKUTargetDelta":{"type":"object","properties":{"monthly_net_savings":{"type":"number","description":"Monthly net savings under this target's resolved candidate vs running on-demand. Equals `commitment_financials_monthly_rate.commitment_savings.net` when a candidate resolved; 0 when `actual_term_reason='no_alternative'` (no commitment, you stay on-demand)."},"monthly_commitment_cost":{"type":"number","description":"Monthly commitment cost under this target's resolved candidate. 0 when no alternative resolved."},"upfront_cost":{"type":"number","description":"One-time upfront dollars under this target's resolved candidate. 0 when no alternative resolved. NOT a rate."}},"required":["monthly_commitment_cost","monthly_net_savings","upfront_cost"],"additionalProperties":false},"CatalogSKUResolution":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid"},"actual_term":{"type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"]}},"required":["actual_payment_option","actual_term","actual_term_reason","sku_id"],"additionalProperties":false},"CatalogSKUOfferComparisonRow":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid","description":"The CatalogSKU id compared."},"quantity":{"type":"integer","description":"Requested catalog quantity."},"covered_quantity":{"type":"number","description":"Catalog quantity covered after provider package-size and normalized-unit rounding. May exceed quantity when offers are sold in indivisible blocks."},"ondemand_baseline":{"description":"On-demand reference point. Compare against each candidate's `commitment_financials_monthly_rate.commitment_cost.total` to see the absolute savings, or read `discount_rate` for the relative figure.","allOf":[{"$ref":"#/components/schemas/CatalogSKUOndemandBaseline"}]},"candidates":{"type":"array","description":"All (offer, lease) pairs available for this SKU at the requested quantity, filtered to the requested contract_terms and payment_options. Ordered by descending discount_rate.","items":{"$ref":"#/components/schemas/CatalogSKUOfferComparisonEntry"}},"targets":{"type":"array","description":"One entry per requested (contract_term, payment_option) target — what the SKU resolves to under that hypothetical, with `actual_term_reason` explaining whether it was an exact match, a fallback to the closest shorter term, or no alternative. Mirrors the line-item endpoint's `hypothetical_totals` shape within this per-SKU response row. The headline 'should I do this' answer per target is `delta_vs_ondemand.monthly_net_savings`.","items":{"$ref":"#/components/schemas/CatalogSKUTarget"}}},"required":["candidates","covered_quantity","ondemand_baseline","quantity","sku_id","targets"],"additionalProperties":false},"CatalogSKUOndemandBaseline":{"type":"object","properties":{"monthly_cost":{"type":"number","description":"Average monthly on-demand cost for covered_quantity. Hourly rates are multiplied by 730; day, month, and year units are normalized to the same average-month basis."},"ondemand_usage_unit":{"type":"string","description":"Unit of measurement for on-demand usage (e.g. 'Hrs').","nullable":true},"ondemand_usage_price":{"type":"number","description":"Per-unit on-demand price in USD."}},"required":["monthly_cost","ondemand_usage_price"],"additionalProperties":false},"CatalogSKUOfferComparisonEntry":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid","description":"Commitment offer id."},"offer":{"description":"Full offer details (type, region, instance, payment_option, etc).","allOf":[{"$ref":"#/components/schemas/CommitmentOffer"}]},"lease_menu_item_id":{"type":"string","format":"uuid","description":"Lease attached to this candidate, or null for a native (non-Archera) commitment.","nullable":true},"selected_amount":{"type":"number","description":"Commitment amount this candidate would be sized to — unit count for RIs / unit-based CUDs, dollar-per-hour rate for Savings Plans / spend-based CUDs. Match the underlying offer.type to interpret."},"contract_term":{"description":"Effective commitment term — derived from the lease lockin hours when `lease_menu_item_id` is set (e.g. 'one_year_gris'), else from the offer's own duration (e.g. 'one_year', 'three_year'). The real lock-in period, not the offer's raw duration.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Payment option (no_upfront / partial_upfront / all_upfront).","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"discount_rate":{"type":"number","description":"Discount rate vs on-demand (0-1)."},"breakeven_days":{"type":"number","description":"Days until this candidate pays for itself; null if undefined.","nullable":true},"commitment_upfront_cost":{"type":"number","description":"One-time dollars at signing for this candidate. NOT a rate — do not sum with monthly-rate fields."},"commitment_financials_monthly_rate":{"description":"Projected economics as 730-hour monthly rates, same shape as line items / plans. `commitment_savings.net` is the headline savings vs running on-demand.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]}},"required":["breakeven_days","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","discount_rate","lease_menu_item_id","offer","offer_id","payment_option","selected_amount"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":"string","description":"Cloud region (e.g. 'us-east-1')","nullable":true},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":"string","description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans","nullable":true},"instance_family":{"type":"string","description":"Instance family (e.g. 'm5'), null for some commitment types","nullable":true},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":"string","enum":["standard","convertible",null],"nullable":true},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"plan_type":{"type":"string","description":"Plan type (e.g. 'Compute', 'EC2Instance')","nullable":true},"product_description":{"type":"string","description":"Product description (e.g. 'Linux/UNIX')","nullable":true},"display_name":{"type":"string","description":"Human-readable offer name","nullable":true},"guaranteed_display_name":{"type":"string","description":"Offer name when purchased as an Archera Guaranteed Commitment","nullable":true},"is_flexible":{"type":"boolean","description":"Whether the commitment has instance size flexibility","nullable":true}},"additionalProperties":false},"CatalogSKUTarget":{"type":"object","properties":{"contract_term":{"description":"Requested contract term for this hypothetical.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"payment_option":{"description":"Requested payment option for this hypothetical.","type":"string","enum":["no_upfront","partial_upfront","all_upfront"]},"actual_term":{"description":"The contract term that actually resolved. Equals `contract_term` when an exact match exists; otherwise the longest term shorter than the target with the same payment option. Null when no alternative exists for the requested (term, payment) pair.","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"actual_payment_option":{"description":"Payment option of the resolved candidate. Equals `payment_option` whenever a candidate resolved (resolution preserves payment option); null when no alternative.","type":"string","enum":["no_upfront","partial_upfront","all_upfront",null],"nullable":true},"actual_term_reason":{"type":"string","enum":["exact_match","fallback_closest_shorter","no_alternative"],"description":"Why this target landed at `actual_term`. `exact_match` = the SKU offers exactly this (term, payment). `fallback_closest_shorter` = no exact match; resolved to the longest term shorter than target with the same payment option (GRI variant preferred when same duration). `no_alternative` = nothing qualifies; surfaced explicitly so the agent can flag to the user that this (term, payment) combination doesn't exist for the SKU."},"candidate":{"description":"The resolved (offer, lease) candidate, or null when `actual_term_reason='no_alternative'`. Same shape as entries in `candidates[]` — the agent can quote `discount_rate`, `breakeven_days`, etc. directly off this nested entry.","anyOf":[{"$ref":"#/components/schemas/CatalogSKUOfferComparisonEntry"},{"type":"object","nullable":true}]},"commitment_financials_monthly_rate":{"description":"Resolved candidate's 730-hour monthly-rate financials, lifted to the top level so the agent can read the same paths as on the line-item endpoint's `hypothetical_totals[i]`. All-zero when `actual_term_reason='no_alternative'`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}]},"commitment_upfront_cost":{"type":"number","description":"Resolved candidate's one-time upfront cost. 0 when no alternative resolved. NOT a rate."},"delta_vs_ondemand":{"description":"Axis-by-axis difference vs the on-demand baseline. Analogous to `delta_vs_current` on the line-item endpoint, but the baseline is on-demand (zero commitment) so each field equals the resolved candidate's value directly.","allOf":[{"$ref":"#/components/schemas/CatalogSKUTargetDelta"}]}},"required":["actual_payment_option","actual_term","actual_term_reason","candidate","commitment_financials_monthly_rate","commitment_upfront_cost","contract_term","delta_vs_ondemand","payment_option"],"additionalProperties":false},"SkippedCatalogSKU":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid"},"reason":{"type":"string"}},"required":["reason","sku_id"],"additionalProperties":false}}}}
```

## The OrganizationMembership object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"OrganizationMembership":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID. Pass as `org_id` to other tools."},"name":{"type":"string","description":"Human-readable organization name."},"domain":{"type":"string","description":"Email domain associated with the org (e.g. 'acme.com'), or null if unset. For other org-management fields (postal address, deactivation flag, created_at), use `get_organization` on a specific `org_id`.","nullable":true},"role":{"type":"string","enum":["user","admin","support","cloud_rep","restricted_user"],"description":"Caller's role in this org: 'user', 'admin', 'support', 'cloud_rep', or 'restricted_user'. Staff users are reported as 'admin' for every active org."},"kind":{"description":"How the caller has access: 'direct' (regular member), 'staff' (staff-level access to every active org), or 'partnership' (inherited via a channel partnership).","enum":["direct","staff","partnership"]},"is_primary":{"type":"boolean","description":"True for the org the caller's tokens default to when no `org_id` is passed. Matches the earliest-joined direct membership returned by `User.active_memberships`."},"denied_permissions":{"type":"array","description":"List of `Resource:action` strings the caller's role is denied (e.g. 'PurchasePlanV2:execute'). Anything not listed is permitted. Use to gate write/destructive recommendations.","items":{"type":"string"}}},"required":["denied_permissions","id","is_primary","kind","name","role"],"additionalProperties":false}}}}
```

## The Address object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"Address":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true,"description":"Address identifier."},"line1":{"type":"string","description":"Street address, line 1."},"line2":{"type":"string","default":null,"description":"Street address, line 2 (optional).","nullable":true},"city":{"type":"string","description":"City."},"state":{"type":"string","description":"State / region / province."},"zip":{"type":"string","description":"Postal / ZIP code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB')."}},"required":["city","country","line1","state","zip"],"additionalProperties":false}}}}
```

## The OrganizationDetail object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"OrganizationDetail":{"type":"object","properties":{"id":{"type":"string","readOnly":true,"description":"Organization ID."},"name":{"type":"string","description":"Organization name. Unique across the platform."},"domain":{"type":"string","description":"Email domain associated with the org (e.g. 'acme.com'). Used for domain-based onboarding flows.","nullable":true},"created_at":{"type":"string","format":"date-time","readOnly":true,"description":"When the org was created."},"primary_address":{"description":"The org's primary postal address (optional).","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"required":["name"],"additionalProperties":false},"Address":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true,"description":"Address identifier."},"line1":{"type":"string","description":"Street address, line 1."},"line2":{"type":"string","default":null,"description":"Street address, line 2 (optional).","nullable":true},"city":{"type":"string","description":"City."},"state":{"type":"string","description":"State / region / province."},"zip":{"type":"string","description":"Postal / ZIP code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB')."}},"required":["city","country","line1","state","zip"],"additionalProperties":false}}}}
```

## The UpdateOrganization object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"UpdateOrganization":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"New organization name."},"domain":{"type":"string","minLength":1,"description":"New email domain, or null to clear.","nullable":true},"primary_address":{"description":"Replacement primary address. Send the full address object. Pass null to clear the existing address.","anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","nullable":true}]}},"additionalProperties":false},"Address":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true,"description":"Address identifier."},"line1":{"type":"string","description":"Street address, line 1."},"line2":{"type":"string","default":null,"description":"Street address, line 2 (optional).","nullable":true},"city":{"type":"string","description":"City."},"state":{"type":"string","description":"State / region / province."},"zip":{"type":"string","description":"Postal / ZIP code."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code (e.g. 'US', 'GB')."}},"required":["city","country","line1","state","zip"],"additionalProperties":false}}}}
```


# Help Center

Welcome to the Archera Help Center. Find answers to common questions, guides for getting started, and in-depth documentation on all Archera features.

## Getting Started

New to Archera? Start here to understand what Archera does and how it can save you money on cloud commitments.

* [Archera Overview](/help-center/getting-started/archera-overview)
* [Product Overview](/help-center/getting-started/product-overview)
* [Platform Features & Modules](/help-center/getting-started/platform-features)
* [What Cloud Services Does Archera Support?](/help-center/getting-started/supported-services)
* [What Category Is Archera In?](/help-center/getting-started/archera-category)

## User Guide

Step-by-step guides for using the Archera platform.

* [Archera QuickStart Guide (AWS)](/help-center/user-guide/quickstart-aws)
* [Commitment Planner](/help-center/user-guide/commitment-planner)
* [Commitment Inventory](/help-center/user-guide/commitment-inventory)
* [Segment Dashboard](/help-center/user-guide/segment-dashboard)

## Guaranteed Commitments

Learn about Archera’s flagship insurance-backed cloud commitment product.

* [What are Guaranteed Commitments?](/help-center/guaranteed-commitments/what-are-guaranteed-commitments)
* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)
* [What are Guaranteed Commitment Allowances?](/help-center/guaranteed-commitments/allowances)

## Onboarding

Guides for connecting your cloud accounts to Archera.

* [AWS Onboarding](/help-center/aws-onboarding/aws)
* [GCP Onboarding](/help-center/gcp-onboarding/gcp)
* [Azure Onboarding](/help-center/azure-onboarding/azure)

## Security

How Archera securely accesses your cloud environment.

* [How Does Archera Access my AWS Environment?](/help-center/sign-in-and-security/aws-access)
* [How Does Archera Access My Azure Environment?](/help-center/sign-in-and-security/azure-access)
* [How Long Is My Data Retained?](/help-center/sign-in-and-security/data-retention)

## Billing

Understand how Archera billing works.

* [Billing and GRIs](/help-center/billing/billing-and-gris)
* [How Customers Pay Archera](/help-center/billing/how-customers-pay)
* [AWS Billing](/help-center/billing/aws-billing)
* [Azure Billing](/help-center/billing/azure-billing)

## FAQ

* [Does Archera Help with Underutilized Infrastructure & Right-Sizing?](/help-center/faq/underutilized-rightsizing)
* [Could Archera Change or Impact My Application?](/help-center/faq/could-impact-application)
* [How Do I Audit Archera?](/help-center/faq/audit)
* [AWS FAQ](/help-center/aws-faq/why-not-cost-explorer)

## Contact Support

Can’t find what you’re looking for? Reach out to us at <support@archera.ai>.


# What is Archera?

Cloud cost optimization platform that reduces spending by 20-30% through intelligent commitment management

Archera is a **free cloud cost optimization platform** that helps organizations reduce their cloud spending by **20-30%** through intelligent commitment management across AWS, Azure, and Google Cloud.

### ​The Problem We Solve <a href="#the-problem-we-solve" id="the-problem-we-solve"></a>

Cloud costs are spiraling out of control for most organizations:

* **On-demand pricing** is the most expensive way to run cloud infrastructure
* **Native commitment tools** are complex, risky, and lack flexibility
* **Multi-cloud management** requires juggling multiple cost tools and strategies
* **Long-term commitments** (1-3 years) create risk when business needs change

### ​How Archera Helps <a href="#how-archera-helps" id="how-archera-helps"></a>

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Intelligent Optimization</strong></td><td><p><strong>AI-Powered Analysis</strong></p><ul><li>Analyzes your actual usage patterns</li><li>Identifies optimal commitment strategies</li><li>Provides risk-adjusted recommendations</li><li>Continuously optimizes over time</li></ul></td></tr><tr><td><strong>Risk Protection</strong></td><td><p><strong>Guaranteed Commitments</strong></p><ul><li>30-day minimum terms (vs 1-3 years native)</li><li>Downside Protection</li><li>Insurance against underutilization</li><li>Transfer flexibility between accounts</li></ul></td></tr><tr><td><strong>Multi-Cloud Unity</strong></td><td><p><strong>Unified Management</strong></p><ul><li>Single platform for all cloud providers</li><li>Cross-cloud optimization strategies</li><li>Consolidated reporting and analytics</li><li>Simplified cost governance</li></ul></td></tr></tbody></table>

### ​Who Uses Archera? <a href="#who-uses-archera" id="who-uses-archera"></a>

<details open>

<summary>Direct Customers</summary>

**Organizations optimizing their own cloud costs**

Use Archera’s free platform to analyze your cloud spending, get intelligent recommendations, and implement risk-free commitments with flexible terms.

</details>

<details open>

<summary>Channel Partners</summary>

**Partners managing multiple customer organizations**

Use the Partner API to onboard customers, manage their optimization strategies, and create marketplace offers through programs like AWS CPPO, Microsoft MPO or ISV-to-CSP Private Offer, or Google MCPO.

</details>

## ​API Overview <a href="#api-overview" id="api-overview"></a>

### ​Which APIs Do You Need? <a href="#which-apis-do-you-need" id="which-apis-do-you-need"></a>

<details open>

<summary>Partners - Use Both APIs</summary>

**As a channel partner, you’ll use BOTH APIs:**

**Partner API (v2)** for:

* Registering new customer organizations
* Managing customer onboarding workflows
* Setting up cloud integrations (AWS CloudFormation, Azure auth)
* Tracking partner-specific metrics

**Public API (v1)** for:

* Accessing each customer’s commitment plans and metrics
* Retrieving cost optimization data for reporting
* Managing commitment plans on behalf of customers
* Building customer-facing dashboards

**Authentication:** Partner API key works for both APIs

</details>

<details open>

<summary>Direct Customers - Use Public API Only</summary>

**As a direct customer, you typically only need:**

**Public API (v1)** for:

* Accessing your organization’s commitment plans
* Retrieving cost and utilization metrics
* Integrating with internal tools and dashboards
* Automating cost optimization workflows

**Authentication:** Standard API key from your Archera account

</details>

## ​Ready to Get Started? <a href="#ready-to-get-started" id="ready-to-get-started"></a>

### ​Learn More About Archera <a href="#learn-more-about-archera" id="learn-more-about-archera"></a>

{% stepper %}
{% step %}
**Understand Rate Optimization**

Learn how rate optimization works and why it’s more effective than usage optimization

[What is Rate Optimization? →](https://github.com/reserved-ai/archera-public-docs/blob/main/public/HelpCenter/rate-optimization.md)
{% endstep %}

{% step %}
**Discover Insured Commitments**

See how Archera’s guaranteed commitments eliminate the risks of traditional cloud commitments

[Learn About Insured Commitments →](https://github.com/reserved-ai/archera-public-docs/blob/main/public/HelpCenter/insured-commitments.md)
{% endstep %}

{% step %}
**Start Your Free Account**

Connect your cloud billing data and begin optimizing within 24-48 hours

[Sign Up with Archera →](https://github.com/reserved-ai/archera-public-docs/blob/main/public/HelpCenter/getting-started/how-to-sign-up-with-archera.md)
{% endstep %}
{% endstepper %}

### ​API Integration Opportunities <a href="#api-integration-opportunities" id="api-integration-opportunities"></a>

Once you understand Archera’s value, here’s how you can integrate it programmatically into your workflows:

<details open>

<summary>Custom Cost Dashboards</summary>

**Build Internal Reporting Tools**

Use the Public API to create custom dashboards that show:

* Real-time cost optimization metrics
* Commitment utilization and performance
* Savings projections and ROI analysis
* Multi-cloud cost visibility in your BI tools

**API Endpoints:** `/commitment-plans`, `/metrics`, `/cost-analysis`

[Explore Public API →](https://docs.archera.ai/api-reference/public-api/public-api-reference)

</details>

<details open>

<summary>Automated Optimization Workflows</summary>

**Integrate Cost Optimization into CI/CD**

Automate commitment purchasing and optimization:

* Trigger commitment purchases based on usage patterns
* Set up automated alerts for optimization opportunities
* Integrate with infrastructure-as-code workflows
* Create approval workflows for large commitments

**API Endpoints:** `/commitment-plans/purchase`, `/automation-policies`, `/recommendations`

[View API Examples →](#quick-api-examples)

</details>

<details open>

<summary>Multi-Customer Management (Partners)</summary>

**Scale Cost Optimization Across Customers**

Use the Partner API to manage multiple customer organizations:

* Programmatically onboard new customers
* Deploy cloud integrations at scale
* Generate customer-specific optimization reports
* Track partner revenue and performance metrics

**API Endpoints:** `/organizations`, `/integrations`, `/partner-metrics`

[Partner API Documentation →](https://docs.archera.ai/api-reference/partner-api/partner-api)

</details>

<details open>

<summary>AWS Marketplace Integration</summary>

**Create CPPO Offers Programmatically**

Automate AWS Marketplace offer creation:

* Use AWS Catalog API to create CPPO offers
* Integrate with Archera’s resale authorization
* Track marketplace performance and revenue
* Manage offer lifecycle programmatically

**Implementation:** AWS Catalog API + Archera Partner API

[CPPO Guide →](https://docs.archera.ai/help-center/partner-guides/create-cppo-offers-for-archera-subscription)

</details>

<details open>

<summary>Cost Data Export &#x26; Analytics</summary>

**Extract Data for Advanced Analytics**

Pull Archera data into your data warehouse:

* Export commitment and utilization data
* Integrate with existing FinOps workflows
* Build predictive cost models
* Create custom allocation and chargeback systems

**API Endpoints:** `/export`, `/utilization-data`, `/cost-allocation`

[Data Export Examples →](#quick-api-examples)

</details>

### ​Quick API Examples <a href="#quick-api-examples" id="quick-api-examples"></a>

Get started with these common API integration patterns:

<details open>

<summary>Get Commitment Recommendations</summary>

**Retrieve AI-powered optimization recommendations**

```
curl -X GET "https://api.archera.ai/v1/recommendations" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

</details>

<details open>

<summary>Track Cost Savings</summary>

**Monitor your optimization performance**

```
curl -X GET "https://api.archera.ai/v1/metrics/savings?period=30d" \
  -H "x-api-key: YOUR_API_KEY"
```

</details>

<details open>

<summary>Create Customer Organization (Partners)</summary>

**Onboard a new customer via Partner API**

```
curl -X POST "https://api.archera.ai/v2/organizations" \
  -H "x-api-key: YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Company",
    "email": "admin@customer.com",
    "cloud_providers": ["aws", "azure"]
  }'
```

</details>

### ​ <a href="#explore-full-api-documentation" id="explore-full-api-documentation"></a>


# How to Sign Up with Archera

Get started with Archera’s platform to begin optimizing your cloud costs through intelligent commitment management

Getting started with Archera is straightforward and designed to have you optimizing costs within minutes. Follow this guide to set up your account and begin your cloud cost optimization journey.

### ​Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before getting started, ensure you have:

<table data-card-size="large" data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><p><strong>Cloud Account Access</strong></p><p><strong>Account Permissions</strong></p><ul><li>Cloud account with billing access (AWS, Azure, or GCP)</li><li>Ability to create necessary integrations</li><li>Cost and usage data access</li></ul></td></tr><tr><td><p><strong>Cost Visibility Setup</strong></p><p><strong>Cost Management Tools</strong></p><ul><li>AWS: Cost and Usage Reports (CUR) configured</li><li>Azure: Cost Management + Billing enabled</li><li>GCP: Billing export configured</li><li>Basic understanding of your spending patterns</li></ul></td></tr><tr><td><p><strong>Basic Understanding</strong></p><p><strong>Cloud Knowledge</strong></p><ul><li>Familiarity with your cloud services</li><li>Understanding of your workload patterns</li><li>Desire to optimize cloud costs</li></ul></td></tr><tr><td><p><strong>Baseline Analysis</strong></p><p><strong>Current State Knowledge</strong></p><ul><li>Knowledge of top spending services</li><li>Understanding of usage patterns</li><li>Existing cost monitoring practices</li></ul></td></tr></tbody></table>

{% hint style="info" %}
**Recommended**: Set up native cost management tools (AWS Cost Explorer, Azure Cost Management, GCP Billing) before connecting to Archera. This provides baseline understanding and enables better optimization decisions.
{% endhint %}

### ​Step 1: Create Your Archera Account <a href="#step-1-create-your-archera-account" id="step-1-create-your-archera-account"></a>

{% stepper %}
{% step %}
**Navigate to Archera**

Go to [app.archera.ai](https://app.archera.ai/) and click “Sign Up” to create your account

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/signup-archera.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=b0603dcb3fdb4ce79183af18e0c9ec97" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Provide Account Details**

Enter your email, create a password, and provide basic organization information
{% endstep %}

{% step %}
**Verify Your Email**

Check your inbox for a verification email and click the confirmation link
{% endstep %}

{% step %}
**Complete Profile Setup**

Add your name, role, and organization details to complete your profile
{% endstep %}
{% endstepper %}

### ​Step 2: Connect Your Cloud Provider <a href="#step-2-connect-your-cloud-provider" id="step-2-connect-your-cloud-provider"></a>

Once your account is created, you’ll need to connect your cloud environment. Archera supports AWS, Azure, and Google Cloud Platform.

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/choose-provider-step.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=8a8d30ea9d2428d9647103374166622c" alt=""><figcaption></figcaption></figure>

#### ​Cloud Provider Integration <a href="#cloud-provider-integration" id="cloud-provider-integration"></a>

Archera uses secure, native integration methods for each cloud provider:

<details open>

<summary>AWS Integration</summary>

**CloudFormation Deployment:**

1. **Launch CloudFormation Stack**: Pre-configured template for secure integration
2. **IAM Role Creation**: Read-only role for cost analysis
3. **Minimal Permissions**: Only cost optimization permissions
4. **No Infrastructure Access**: Never accesses running workloads

   ![CloudFormation Screenshot](https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/cloudformation-screenshot.png?fit=max\&auto=format\&n=cCBfcsubiIlPNh4r\&q=85\&s=835ec26f9ca18d75cd3bc8780d1179df)

</details>

<details open>

<summary>Azure Integration</summary>

**Service Principal Setup:**

1. **App Registration**: Create service principal in Azure AD
2. **Reader Permissions**: Billing and cost management access
3. **Secure Connection**: OAuth-based authentication
4. **Cost Data Only**: No access to operational resources

</details>

<details open>

<summary>Google Cloud Integration</summary>

**Service Account Configuration:**

1. **Service Account**: Create dedicated service account
2. **Billing Permissions**: Cloud billing and asset inventory access
3. **JSON Key**: Secure key-based authentication
4. **Read-Only Access**: No modification permissions

</details>

<details open>

<summary>What Archera Accesses</summary>

**Required Data Access:**

* **Cost and Usage Data**: To analyze spending patterns
* **Resource Information**: To recommend appropriate commitments
* **Billing Information**: To calculate potential savings

**What Archera NEVER Accesses:**

* Your application data or workloads
* Running instances or services
* Security configurations
* Any operational infrastructure

</details>

#### ​Connection Process <a href="#connection-process" id="connection-process"></a>

{% stepper %}
{% step %}
**Select Cloud Provider**

Choose your cloud provider (AWS, Azure, or Google Cloud) from the integration options
{% endstep %}

{% step %}
**Follow Provider Instructions**

Each provider has specific integration steps guided by the platform
{% endstep %}

{% step %}
**Review Permissions**

Review the access permissions that will be granted
{% endstep %}

{% step %}
**Complete Integration**

Confirm the connection and verify successful integration
{% endstep %}
{% endstepper %}

### ​Step 3: Initial Cost Analysis <a href="#step-3-initial-cost-analysis" id="step-3-initial-cost-analysis"></a>

After connecting your cloud account, Archera will begin analyzing your usage:

{% hint style="info" %}
**Onboarding Process**: Connection is completely free and purely to access your billing data so Archera can make accurate recommendations based on your actual usage numbers. After connecting, it takes **24-48 hours** to unlock the full platform as historical data is processed.
{% endhint %}

#### ​Data Processing Timeline <a href="#data-processing-timeline" id="data-processing-timeline"></a>

#### &#x20;<a href="#data-processing-timeline" id="data-processing-timeline"></a>

<table data-card-size="large" data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><p><strong>Initial Connection</strong></p><p><strong>5-10 Minutes</strong></p><ul><li>Account connection verification</li><li>Basic cost data import</li><li>Infrastructure discovery</li></ul></td></tr><tr><td><p><strong>Full Platform Access</strong></p><p><strong>24-48 Hours</strong></p><ul><li>Historical usage analysis</li><li>Savings opportunity identification</li><li>Complete platform functionality unlocked</li></ul></td></tr></tbody></table>

#### ​What You’ll See First <a href="#what-youll-see-first" id="what-youll-see-first"></a>

Once initial processing completes, you’ll have access to:

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/immediate-savings-analysis.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=8690757d60cf9321a5502bdd7094c0be" alt=""><figcaption></figcaption></figure>

1. **Immediate Savings Analysis**: Quick wins for covering on-demand usage with short-term commitments
2. **Commitment Planner**: Three default strategies (Recommended, Balanced, High Savings)
3. **Cost Dashboard**: Overview of your current spending and optimization opportunities

### ​Step 4: Explore Your Savings Opportunities <a href="#step-4-explore-your-savings-opportunities" id="step-4-explore-your-savings-opportunities"></a>

#### ​Immediate Savings Analysis <a href="#immediate-savings-analysis" id="immediate-savings-analysis"></a>

Your first view will show immediate opportunities to cover on-demand usage with 30-day commitments:

* **Stop the Bleeding**: Identify on-demand resources that should have commitments
* **Quick Implementation**: Apply 30-day commitments for immediate savings
* **Risk-Free Start**: Begin optimization without long-term commitments

#### ​Commitment Planner <a href="#commitment-planner" id="commitment-planner"></a>

Explore three pre-configured commitment strategies:

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/default-commitment-plans.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=7994b668ed1c319788cb26aca1a5b558" alt=""><figcaption></figcaption></figure>

<details open>

<summary>Recommended Plan</summary>

**Focus**: Maximum flexibility with immediate savings

* Primarily 30-day guaranteed commitments
* Lowest risk, moderate savings
* Perfect for getting started

</details>

<details open>

<summary>Balanced Plan</summary>

**Focus**: Optimal balance of savings and flexibility

* All reservable services included
* Mix of 30-day and 1-year commitments
* Most popular choice for ongoing optimization

</details>

<details open>

<summary>High Savings Plan</summary>

**Focus**: Maximum cost reduction

* 3-year commitments with upfront payments
* Highest savings potential
* Reduced flexibility, maximum discounts

</details>

### ​Step 5: Implement Your First Plan <a href="#step-5-implement-your-first-plan" id="step-5-implement-your-first-plan"></a>

#### ​Applying a Commitment Plan <a href="#applying-a-commitment-plan" id="applying-a-commitment-plan"></a>

#### &#x20;<a href="#applying-a-commitment-plan" id="applying-a-commitment-plan"></a>

{% stepper %}
{% step %}
**Select Your Strategy**

Choose from Recommended, Balanced, or High Savings plans
{% endstep %}

{% step %}
**Review Details**

Click “View Details” to see specific commitments and covered infrastructure
{% endstep %}

{% step %}
**Customize if Needed**

Edit individual line items or create custom plans as desired
{% endstep %}

{% step %}
**Apply Plan**

Click “Apply Plan” to implement your chosen strategy and start saving
{% endstep %}
{% endstepper %}

#### ​Setting Up Automation (Optional) <a href="#setting-up-automation-optional" id="setting-up-automation-optional"></a>

Enable automation policies for hands-off optimization:

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/automation-toggle.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=1620a83cff379bcac1911600701e381a" alt=""><figcaption></figcaption></figure>

1. **Configure Thresholds**: Set minimum savings amounts to trigger automation
2. **Choose Cadence**: Select weekly, monthly, or quarterly evaluation
3. **Monitor Performance**: Track automated savings and adjust as needed
4. **Maintain Control**: Cancel or modify policies anytime

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/automation-modal.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=881cbcc527dd0e8705f6b40e0fdd4bf5" alt=""><figcaption></figcaption></figure>

### ​Step 6: Ongoing Management <a href="#step-6-ongoing-management" id="step-6-ongoing-management"></a>

#### ​Platform Features <a href="#platform-features" id="platform-features"></a>

Once you’re up and running, take advantage of:

<table data-card-size="large" data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><p><strong>Custom Plan Creation</strong></p><p><strong>Build Your Own Strategy</strong></p><ul><li>Create plans tailored to your needs</li><li>Mix commitment types and terms</li><li>Save and share plans with your team</li></ul></td></tr><tr><td><p><strong>Performance Monitoring</strong></p><p><strong>Track Your Success</strong></p><ul><li>Monitor utilization and savings</li><li>View breakeven timelines</li><li>Analyze coverage across services</li></ul></td></tr><tr><td><p><strong>Team Collaboration</strong></p><p><strong>Multi-User Support</strong></p><ul><li>Invite team members</li><li>Set permissions and roles</li><li>Share plans and reports</li></ul></td></tr><tr><td><p><strong>API Integration</strong></p><p><strong>Programmatic Access</strong></p><ul><li>REST API for custom integrations</li><li>Export data for reporting</li><li>Automate workflows</li></ul></td></tr></tbody></table>

#### ​Best Practices <a href="#best-practices" id="best-practices"></a>

1. **Start Small**: Begin with 30-day commitments to understand the platform
2. **Monitor Regularly**: Review savings and utilization weekly
3. **Use Automation**: Enable policies once comfortable with manual optimization
4. **Plan Ahead**: Consider business changes when selecting commitment terms

<figure><img src="https://mintcdn.com/archera/cCBfcsubiIlPNh4r/images/onboarding-end.png?fit=max&#x26;auto=format&#x26;n=cCBfcsubiIlPNh4r&#x26;q=85&#x26;s=a071953270bf4c36395d5c22ff11cd32" alt=""><figcaption></figcaption></figure>

### ​Security and Compliance <a href="#security-and-compliance" id="security-and-compliance"></a>

Archera maintains enterprise-grade security:

* **SOC 2 Type II Compliance**: Audited security controls and processes
* **Least Privilege Access**: Minimal required permissions for cost optimization
* **No Data Storage**: Cost data processed in real-time, not stored
* **Encryption**: All data transmitted using industry-standard encryption

{% hint style="info" %}
**Free Platform**: Archera’s platform is completely free to use. Connection is purely to access billing data for accurate recommendations. There are no hidden fees, and you keep 100% of your optimized savings. Full platform access is available 24-48 hours after connecting your cloud account.
{% endhint %}


# Supported Reservable Services

Comprehensive list of all cloud services supported by Archera’s platform across AWS, Azure, and Google Cloud

Archera’s platform supports **all reservable services** across major cloud providers. Customers can purchase and manage commitments for any service that supports reservations.

### ​AWS Reservable Services <a href="#aws-reservable-services" id="aws-reservable-services"></a>

Archera supports all AWS services that offer reservations or commitments, including:

* **Compute**: EC2 Reserved Instances (all types), Savings Plans, Lambda
* **Database**: RDS, ElastiCache, DynamoDB Reserved Capacity
* **Analytics**: Redshift, OpenSearch Reserved Instances
* **Storage**: EBS, S3 storage classes

{% embed url="<https://docs.aws.amazon.com/whitepapers/latest/cost-optimization-reservation-models/reservation-models-for-other-aws-services.html>" %}

### ​Azure Reservable Services <a href="#azure-reservable-services" id="azure-reservable-services"></a>

Archera supports all Azure services that offer reservations, including:

* **Compute**: Virtual Machine Reserved Instances (all VM series including D, E, F, G, H, L, M, N series), Azure Dedicated Host, App Service plans, Azure Container Instances
* **Database**: SQL Database (vCore tiers only — DTU tiers are not eligible), Azure Database for MySQL, Azure Database for PostgreSQL, Azure Database for MariaDB (retired September 2025 — do not purchase new reservations), Cosmos DB (all APIs), Azure Cache for Redis (Premium, Enterprise, and Enterprise Flash tiers only)
* **Storage**: Blob storage (all access tiers), Azure Files, Managed Disks (Premium SSD P30–P80 only), Azure NetApp Files
* **Analytics**: Synapse Analytics (SQL pools, Spark pools), Data Factory (pipeline runs, data flows), Azure Databricks (all SKUs), HDInsight clusters
* **AI/ML**: Azure Cognitive Services, Azure Machine Learning compute instances
* **Networking**: VPN Gateway, ExpressRoute circuits, Azure Firewall
* **Other Services**: Azure VMware Solution, Azure Red Hat OpenShift, Azure Spring Apps Enterprise (retirement started March 2025 — verify before committing)

{% embed url="<https://learn.microsoft.com/en-us/azure/cost-management-billing/reservations/save-compute-costs-reservations>" %}

### ​Google Cloud Reservable Services <a href="#google-cloud-reservable-services" id="google-cloud-reservable-services"></a>

Archera supports all Google Cloud services that offer Committed Use Discounts (CUDs), including:

* **Compute**: Compute Engine (all machine types), resource and spend-based CUDs
* **Database**: Cloud SQL (all database engines and configurations)
* **Analytics**: BigQuery slots, Cloud Storage, Dataflow
* **AI/ML**: Vertex AI, Cloud TPU

{% embed url="<https://cloud.google.com/docs/cuds>" %}

### ​Archera Advantages <a href="#archera-advantages" id="archera-advantages"></a>

When customers purchase commitments through Archera’s platform (via CPPO offers), they receive:

<table data-card-size="large" data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><p><strong>Transfer Flexibility</strong></p><p><strong>Account Mobility</strong></p><ul><li>Transfer commitments between accounts</li><li>Reorganize cloud structure without losing savings</li><li>Support for M&#x26;A activities</li></ul></td></tr><tr><td><p><strong>Risk Mitigation</strong></p><p><strong>Investment Protection</strong></p><ul><li>Insurance against unused capacity</li><li>Guaranteed savings realization</li><li>Professional management included</li></ul></td></tr><tr><td><p><strong>Multi-Cloud Strategy</strong></p><p><strong>Unified Management</strong></p><ul><li>Single platform for all cloud commitments</li><li>Cross-cloud optimization strategies</li><li>Consolidated reporting and analytics</li></ul></td></tr></tbody></table>

### ​Service Coverage Updates <a href="#service-coverage-updates" id="service-coverage-updates"></a>

#### ​Continuous Expansion <a href="#continuous-expansion" id="continuous-expansion"></a>

Archera’s platform automatically supports new reservable services as cloud providers introduce them:

* **AWS**: New instance types, services, and reservation options are added automatically
* **Azure**: New VM series, database options, and capacity types are supported upon release
* **Google Cloud**: New machine types, services, and commitment options are included immediately

#### ​Notification System <a href="#notification-system" id="notification-system"></a>

Partners and customers are notified when:

* New reservable services become available
* Existing services add new reservation options
* Pricing or terms for reservations change
* Optimization opportunities arise from new service options

{% hint style="info" %}
**For CPPO Partners**: This comprehensive service coverage means your customers can optimize costs for their entire cloud infrastructure through a single Archera subscription, maximizing the value of your marketplace offers.
{% endhint %}

### ​Next Steps <a href="#next-steps" id="next-steps"></a>

### ​Cloud Provider Reservation References <a href="#cloud-provider-reservation-references" id="cloud-provider-reservation-references"></a>

For detailed information about reservable services across cloud providers, consult these comprehensive documentation resources:

#### ​AWS Reserved Instances & Savings Plans <a href="#aws-reserved-instances-and-savings-plans" id="aws-reserved-instances-and-savings-plans"></a>

{% embed url="<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-reserved-instances.html>" %}

{% embed url="<https://docs.aws.amazon.com/savingsplans/latest/userguide/>" %}

{% embed url="<https://aws.amazon.com/aws-cost-management/aws-cost-optimization/reserved-instances/>" %}

{% embed url="<https://docs.aws.amazon.com/whitepapers/latest/cost-optimization-reservation-models/reservation-models-for-other-aws-services.html>" %}

#### ​Google Cloud Committed Use Discounts <a href="#google-cloud-committed-use-discounts" id="google-cloud-committed-use-discounts"></a>

{% embed url="<https://cloud.google.com/docs/cuds>" %}

{% embed url="<https://cloud.google.com/compute/docs/instances/committed-use-discounts-overview>" %}

#### ​Azure Reservations <a href="#azure-reservations" id="azure-reservations"></a>

{% embed url="<https://learn.microsoft.com/en-us/azure/cost-management-billing/reservations/save-compute-costs-reservations>" %}

{% embed url="<https://azure.microsoft.com/en-us/pricing/reserved-capacity>" %}

{% hint style="info" %}
**For Partners**: Understanding these reservation types helps you better assist customers in selecting appropriate CPPO offers. Archera’s platform supports purchasing and managing all these commitment types.
{% endhint %}


# Archera Overview

Archera is an AWS, Azure and GCP cloud cost optimization platform focused on commitment & rate management. The core platform is free for multi-cloud cost observability, modeling/forecasting, management of native commitment options and AWS Well-Architected reviews.

## What Makes Archera Unique

The unique selling proposition is that through the free platform, Archera offers (and automatically underwrites) its unique **"Guaranteed Commitments"** with an insurance-backed guarantee, specifically:

* **Guaranteed Reserved Instances (GRIs)** — for AWS and Azure
* **Guaranteed Savings Plans (GSPs)** — for AWS and Azure
* **Guaranteed Committed Use Discounts (GCUDs)** — for GCP only

These are shorter-term, flexible-term commitments for customers of AWS, Azure, and GCP to utilize and avoid paying list pricing for their cloud usage or entering into the standard 1- and 3-year, fixed-term commitments offered by the three cloud providers.

## How Guaranteed Commitments Work

Mechanically, these Guaranteed or Insured Commitments are created by Archera purchasing one or three year commitments (RIs, SPs or CUDs), typically with no-upfront payment in the customer account, and then overlaying an insurance-backed "moneyback guarantee" on these commitments. This guarantees to the customer that Archera will bear the cost of any unused committed spend, via a rebate or buy-back of the commitment (depending on the commitment type), after a specified term that is less than the term of the underlying commitment (typically 30 days or 1 year).

Customers typically get insured commitment term lengths of **30 days and 1-year** of locked-in spend with 35 and 24 months of flexible coverage after that respectively, while charging a "risk premium" based on the term (and consequently risk that Archera takes on).

**Archera does not impact any infrastructure by design** and only operates at the rate/commitment/contract "layer."

## When to Use Archera

Archera is an excellent tool that customers use typically in one of two scenarios:

1. **When they are unsure that workloads will be up long enough to justify a 1-year commitment.** Archera's 30-day Insured Commitments are a perfect fit because they only need to be locked in for 30 days.
2. **When they are unsure that workloads will be up long enough to justify a 3-year commitment.** Archera's 1-year commitments are a perfect fit because they offer more savings than standard 1-year commitments offered by cloud providers.

Archera offers a **"moneyback guarantee"** so if, after the Archera Insured Commitment term length (30 days or one year), the commitment goes underutilized and results in no savings for the customer, Archera will guarantee to buy that commitment back from the customer or rebate them the cost of that commitment.


# Product Overview

Archera is an **AWS, Azure and GCP cloud cost optimization platform** focused on commitment and rate management. The core platform is free for multi-cloud cost observability, modeling/forecasting, management of native commitment options and architecture reviews.

Our goal at Archera is to enable Engineering and Finance to make smarter decisions around infrastructure planning and commitment purchases. To help teams we have core tools around Segment Views (for Infrastructure and Team Planning) and FinOps views (for purchasing and financial analysis).

## What Makes Archera Unique

The unique selling proposition is that through the free platform Archera offers (and automatically underwrites) its unique **"Guaranteed Commitments"** with an insurance-backed guarantee, specifically:

* **Guaranteed Reserved Instances (GRIs)** — for AWS and Azure
* **Guaranteed Savings Plans (GSPs)** — for AWS and Azure
* **Guaranteed Committed Use Discounts (GCUDs)** — for GCP only

These are shorter-term, flexible-term commitments for customers of AWS, Azure, and GCP to utilize and avoid paying list pricing for their cloud usage or entering into the standard 1- and 3-year, fixed-term commitments offered by the three cloud providers.

### How Guaranteed Commitments Work

Mechanically, these Guaranteed or Insured Commitments are created by Archera purchasing one or three year commitments (RIs, SPs or CUDs), typically with no-upfront payment in the customer account, and then overlaying an **insurance-backed "moneyback guarantee"** on these commitments. This guarantees to the customer that Archera will bear the cost of any unused committed spend via a rebate or buy-back of the commitment (depending on the commitment type) after a specified term that is less than the term of the underlying commitment (typically 30 days or 1 year).

Customers typically get insured commitment term lengths of **30 days and 1-year** of locked-in spend with 35 and 24 months of flexible coverage after that respectively, while charging a "risk premium" based on the term (and consequently risk that Archera takes on).

**Archera does not impact any infrastructure by design** and only operates at the rate/commitment/contract "layer."

### When to Use Archera

Archera is an excellent tool that customers use typically in one of two scenarios:

1. **When they are unsure that workloads will be up long enough to justify a 1-year commitment.** Archera's 30-day Insured Commitments are a perfect fit because they only need to be locked in for 30 days.
2. **When they are unsure that workloads will be up long enough to justify a 3-year commitment.** Archera's 1-year commitments are a perfect fit because they offer more savings than standard 1-year commitments offered by cloud providers.

Archera offers a **"moneyback guarantee"** so if, after the Archera Insured Commitment term length (30 days or one year), the commitment goes underutilized and results in no savings for the customer, Archera will guarantee to buy that commitment back from the customer or rebate them the cost of that commitment.

## Getting Started

To get started, connect your systems to Archera through the [Integrations Page](/help-center/user-guide/settings-integrations).

Once that is complete you can start to build out Segments in the [Segment Dashboard](/help-center/user-guide/segment-dashboard) and [Invite Users](/help-center/user-guide/invite-users).

## Core Application Flows

The Archera application is broken out into two core flows:

1. **Segment Views** — represent Infrastructure and Team Planning
2. **Commitment & Renewal Planning** — used for DevOps and FinOps users who are making commitment purchasing

## Segment Page Walk Throughs

### Segment Dashboard

See [Segment Dashboard Overview](/help-center/user-guide/segment-dashboard).

### Explorer

Segment Explorer connects directly to your cloud provider and pulls costs and other details out of the system. In addition to unique queries for that provider, you can overlay custom KPIs and other metrics to see how you compare. We also have standardized alerting and anomalies to help keep your team on track.

### Planner

Our Segment Planner tool allows Teams to do monthly and quarterly planning. Using your actual cloud spend as a baseline, our tools help your teams create budgets and forecasts for specific scenarios — so you can plan for changes in the business such as increase or decrease of customers or a shift in technology.

### Infrastructure History

[Infrastructure History](/help-center/user-guide/infrastructure-history) allows you to explore your infrastructure at a granular level such as EC2 and Lambda. It also allows you to search on tag information.

### Resource Recommendations

Engineering and FinOps teams can also track the entire lifecycle of infrastructure recommendations — from rightsizing actions being recommended to executed, you have visibility into the goal and stage of the recommendation.

### Settings

Controls Anomaly Detection, Alerts, and Coverage goals for the Segment.

## Related Resources

* [Billing and GRIs (Guaranteed Reserved Instances)](/help-center/billing/billing-and-gris)
* [Azure Billing - How Archera is Billed Through Azure](/help-center/billing/azure-billing)
* [AWS Billing - How Archera is Billed Through AWS](/help-center/billing/aws-billing)
* [What is the lookback period inside commitment planner and when to use it?](/help-center/user-guide/lookback-period)
* [How Does Archera Calculate Commitment Coverage](/help-center/user-guide/commitment-coverage)


# Platform Features & Modules

The Archera platform is divided into the following dashboards and the general areas they fall under.

## Setup

**0. Actionable Savings** — Contains the setup "success" checklist with the steps needed to complete setup of Archera for the given clouds you have installed, and view the initial savings analysis with low-risk, 1-click potential savings once setup is completed.

## Commitments

**1. Commitment Planner** — The core dashboard. Features the ability to submit "purchase plans" for commitments you would like to buy, create and manage custom plans, and view submitted and executed plans. Archera provides three plans by default: "Recommended", "Balanced", and "High Savings."

**2. Commitment Inventory** — Shows all of your commitments and their respective cost, savings, utilization, and locked/unlocked status (only relevant to Archera's Insured Commitments).

**3. Commitment Moneyback** — Shows what commitments are being suggested for buyback or rebate, what commitments have been slated for buyback, and what commitments were bought back or are currently being rebated by Archera. You can also enable buyback automation based on a specific lookback period and dollar threshold.

## Visibility

**4. Cost Attribution** — Allows you to view segments of your infrastructure and their accompanying cost, resource count, and budget. You can also make segments here based on cloud provider and infrastructure rules (service, resource group, region, tags, instance family, operating system, and tenancy).

**5. Cost Explorer** — Similar to AWS's Cost Explorer functionality. Allows you to view costs across time, compare costs across time ranges, group by specific metrics, view costs by metric (amortized, blended, net amortized, net unblended, unblended, normalized usage amount, usage quantity), adjust cost granularity (daily, monthly, yearly), and more.

**6. Infrastructure Inventory** — Shows all resources in your accounts. You can filter infrastructure by many options, including whether they were recently used, uptime, coverage, instance family, instance type, and more. Click through any resource to see additional details about usage.

**7. Savings Breakdown** — Shows gross and net savings across different commitment/service types, along with resource cost and count over time.

**8. Financial Workbench** — Allows you to add the terms of your EDP/PPA (Enterprise Discount Plan / Private Pricing Agreement with AWS) and add any active credit programs from cloud providers.

## Operations

**9. Reporting** — Custom reporting dashboard separated into five different tabs: Cost Explorer, Segment Explorer, Reservation Explorer, Tag Explorer, and Monthly Explorer.

**10. Assessments** — Relates to AWS's WAFR (Well-Architected Framework Report).

**11. Payment Planner** — Shows a log of all payments issued to customers in the form of rebates or credits from Archera.

**12. Forecasting** — Allows you to create custom forecasts based on services and third-party software costs.

## Settings

Along with these dashboards, there are organization settings and user settings portals:

### Organization Settings

* **General** — General settings
* **Users** — Users in the organization
* **SSO** — SSO settings
* **Billing** — Billing settings
* **Invoices** — Invoices
* **Integrations** — Cloud provider integrations to Archera
* **Discounts** — Applicable discounts like EDPs, PPAs, and MACCs
* **Notifications** — Organization level notification settings

### User Settings

* **Account** — User account settings
* **Notifications** — User notification settings
* **API Access** — API settings
* **Comment Templates** — Comment templates for users regarding commitment plans


# What Cloud Services Does Archera Support?

Archera currently supports **AWS** and **Azure** as fully generally available for customers and partners.

**GCP** is currently in private beta. Oracle Cloud, Databricks and a number of the NeoClouds are slated for general availability by the 2nd half of 2026.

Across all clouds Archera is non-infrastructure impacting, meaning its optimizations can be implemented with a few simple clicks and puts none of your infrastructure at risk while also appealing to the finance team's needs for reducing long-term liabilities.

## Related Resources

* [What Category is Archera In?](/help-center/getting-started/archera-category)
* [Archera Overview](/help-center/getting-started/archera-overview)
* [Archera Platform Features & Modules](/help-center/getting-started/platform-features)


# What Category Is Archera In?

Archera offers a free FinOps Platform, however it is the category creator of **Insured Commitments**, which it offers through the platform as first-of-their-kind commitments with an insurance-backed guarantee.

These are technically referred to as **Guaranteed Cloud Commitments** (RIs, SPs, CUDs, PTUs etc.) with the word "Guaranteed" prefacing the underlying commitment type to reflect Archera's insurance-backed guarantee that is attached:

* **GRIs** — Guaranteed Reserved Instances
* **GSPs** — Guaranteed Savings Plans
* **GCUDs** — Guaranteed Committed Use Discounts
* **GPTUs** — Guaranteed Provisioned Throughput Units

You will hear Archera refer to these offerings as **Insured Commitments** (as they are the product that created the category) or **Guaranteed Commitments**, which are Archera's specific implementation.

## Related Resources

* [What are Guaranteed Commitments?](/help-center/guaranteed-commitments/what-are-guaranteed-commitments)
* [What Cloud Services Does Archera Support?](/help-center/getting-started/supported-services)
* [Archera Overview](/help-center/getting-started/archera-overview)


# User Guide

Step-by-step guides and overviews for using every part of the Archera platform.

## Articles in This Section

* [Archera QuickStart Guide (AWS)](/help-center/user-guide/quickstart-aws)
* [Segment Dashboard - Overview](/help-center/user-guide/segment-dashboard)
* [Infrastructure History - Overview](/help-center/user-guide/infrastructure-history)
* [Resource Recommendations - Overview](/help-center/user-guide/resource-recommendations)
* [Commitment Planner - Overview](/help-center/user-guide/commitment-planner)
* [Commitment Inventory](/help-center/user-guide/commitment-inventory)
* [Settings & Integrations - Section Overview](/help-center/user-guide/settings-integrations)
* [How to Create a Custom Purchase or Renewal Plan](/help-center/user-guide/how-to-create-custom-plan)
* [How Does Archera Calculate Commitment Coverage](/help-center/user-guide/commitment-coverage)
* [How Does Commitment Discount Attribution Work](/help-center/user-guide/commitment-attribution)
* [Invite Users and Onboarding Troubleshooting](/help-center/user-guide/invite-users)
* [How Do I Remove or Add a User?](/help-center/user-guide/add-remove-users)
* [What is the Lookback Period?](/help-center/user-guide/lookback-period)
* [What Contract Terms Are Available for AWS?](/help-center/user-guide/contract-terms-aws)
* [Archera's Savings Options](/help-center/user-guide/savings-options)
* [Recommended Plan: Flexible Savings, Minimal Commitment](/help-center/user-guide/recommended-plan)
* [Why is my Dashboard a Day or Two Behind?](/help-center/user-guide/dashboard-day-behind)


# Archera QuickStart Guide (AWS)

Archera is next-generation cloud financial management software that helps companies of all sizes optimize their cloud financial efficiency. In this article we will cover a quick start walkthrough to using Archera with AWS as a service provider.

We'll also look at a few examples of how to use the Archera platform as a starting point to realize value in the form of increased savings, decreased time spent managing cloud resources, and de-risking infrastructure investments.

## Pre-Requisites

* Administrator access to AWS console
* AWS Master Account Number

### Nice To Haves

* Identify a "Commitment Manager" in your organization
* Understand how your infrastructure is organized (e.g. by tags, accounts, etc)
* Enable Compute Optimizer

## Steps Covered in this Guide

1. Register for Archera
2. Connect to your AWS accounts
   * Only organization sub-accounts that contain commitments need to be connected for full commitment visibility and analysis.
3. Purchasing Commitments for uncovered Infrastructure
4. Automating Renewals

## 1. Register on Archera

First, register an account on the Archera application. Fill in your information and click "Start Free Trial."

## 2. Connect to AWS

After Registration, click AWS. This will launch our guided walkthrough for connecting your AWS account to the Archera platform.

The walkthrough should be self explanatory and includes a number of options for methods. The Cloudformation method is the recommended approach, however any will work.

Once complete, please click "Verify Installation" to ensure that the Archera platform can communicate with your AWS.

Once verified — let's next take a look at your commitment coverage information.

## 3. Example: Optimizing Commitment Coverage

Now that we're connected to your account, the Archera platform creates a few Segments by default, including "All Resources." This Segment will allow you to see information about all the infrastructure resources currently deployed in your AWS account.

When you first login, you will be on the Actionable Savings page. This page gives you an overview of your:

* Current monthly cost
* Monthly Cost using Archera's recommended plan
* Days to break even with plan
* Current coverage level

Click "Explore More Commitment Plans" at the bottom of the card to dive into the details. The summaries include relevant details about commitment types, potential savings, and overall spend commitments. Please see [Commitment Planner](/help-center/user-guide/commitment-planner) and [Creating Custom Purchase Plans](/help-center/user-guide/how-to-create-custom-plan) for further details.

## 4. Automating Renewals

Lastly, for any existing commitments, Archera can optimize and automate the renewals. The process is very similar to creating a purchase plan, but now we are looking at existing commitments and either renewing them as-is, or optimizing them further with an Archera plan.

To get started, click [Commitment Inventory](/help-center/user-guide/commitment-inventory) from the top level menu.

Next, select the expiring commitments either by clicking the red bars in the chart or selecting the individual commitments from the inventory below.

Once the commitments have been selected click "Create Renewal Plan." This will launch a view to explore pre-built plans, which you can juxtapose against the "Naive Renewal" (i.e. renewing the existing commitments as-is). You can also create a custom plan similar to the Commitment Planner.

## Conclusion

Optimizing your commitment coverage is just one of many use cases for the Archera platform. We encourage you to check out the documentation or reach out to us at <solutions@archera.ai> to see how we can help you optimize your cloud financial management.

## Related Resources

* [Billing and GRIs (Guaranteed Reserved Instances)](/help-center/billing/billing-and-gris)
* [Azure Billing - How Archera is Billed Through Azure](/help-center/billing/azure-billing)
* [AWS Billing - How Archera is Billed Through AWS](/help-center/billing/aws-billing)
* [Product Overview](/help-center/getting-started/product-overview)
* [What is the lookback period inside commitment planner and when to use it?](/help-center/user-guide/lookback-period)


# Segment Dashboard - Overview

Segment Dashboard acts as a diving off point for Teams managing specific aspects of Infrastructure. Segments can represent Product Lines, or specific areas of infrastructure that a team wants to group together to manage. The goal is to help you dive into Costs, Commitments, and Recommendations at a Monthly or Yearly Level. Dev and FinOps owners use the Dashboard as a monthly sync to show progress with Finance.

## Cost Summaries

This section outlines how the Total Cost across the Segment compares to Budgets, Forecasts, and the prior period. The app also breaks out Cost and Savings for the given time period so you can see how your investments are paying off.

You can set Budgets and Forecasts in the Segment Planner.

**Cost Forecast** breaks down the timeseries of high level cost trends against goals for the current time period.

**Cost Trends** breaks out specific services and clicking on one will take you to Segment Explorer, which will show specific segments of the infrastructure with trends.

## Reservations

Archera's automated portfolio matching system will help find the optimal blend of Reservations and other Cost Savings Plans.

**Commitment Coverage** shows you the total amount of Coverage this segment currently has based on Coverable Cost.

**The Exchanges** card gives you savings from commitments you can exchange or change.

**Expiring Commitments** gives you a quick breakdown of upcoming planning that you might need to take. Clicking on Expiring Commitments will take you to our [Commitment Inventory](/help-center/user-guide/commitment-inventory) page where you can set up reminders and automation around purchasing.

## Recommendations

Infrastructure Recommendations such as rightsizing servers or changing configurations can impact your cost. To help track these recommendations, Archera connects to AWS Compute Optimizer and other observability tools with agents deployed in your environment (like Datadog).

**Provider Breakdown and Type Breakdown** provides recommendations by Provider/Source as well as top recommendations by Type. When new recommendations come in they are flagged as **New** and team members can mark the stages from New → Reviewed → Completed.

Recommendations are currently in Beta. If you're interested, contact the team and follow these steps to set up the [Resource Recommendations Page](/help-center/user-guide/resource-recommendations).

## Related Resources

* [Commitment Inventory](/help-center/user-guide/commitment-inventory)
* [Resource Recommendations - Overview](/help-center/user-guide/resource-recommendations)
* [Product Overview](/help-center/getting-started/product-overview)


# Infrastructure History - Overview

**No Infrastructure Left Behind!** The Infrastructure History page acts as a diving off point to see EC2s, Lambda Functions, RDS, Fargate, and other individual resources.

Here you can see Resource Details such as Operating Service and other details provided by the Cloud Provider specifically for this service. You can also see Tags as well as a larger chart to view uptime.

Primarily the Infrastructure History page uses your selected Segment as the initial filter. Additional search options such as Untagged Resources are available to help further refine the search.

## Infrastructure List and Details

Here you can see:

* Usage metrics
* Cost
* Savings
* How Commitments are being applied to the infrastructure

If you have created a segment, it's also a quick way to verify the infrastructure is mapped properly — all the relevant information (accountId, tags, etc.) used in segment creation is available here.

If you have just launched some new Infrastructure, we recommend checking it out in the Infrastructure History page for coverage a few days after launch, as it takes some time for coverage to be applied. AWS and other Cloud Providers will randomly assign commitment coverage to assets.

**Hovering over coverage icons provides more information about:**

* Coverage
* Uptime
* Utilization (if available)

## Search on Multiple Fields

You can search on a number of fields such as:

* Region
* Name
* Operating system

## Searching and Filters

To get more granular you can select core Filters such as:

* Resource Type
* Region
* Service

to drill down on specifically. The mode option of AND/OR either combines the Filters in an AND operator or allows you to search for alternatives with an OR.

Remember this page is initially filtered by Segment at the top — the filters are simply to act as a last-mile search.

**Search Untagged** to add the untagged filter.

Available fields will show up as optional filters. They vary between cloud provider, but we provide Region, AccountId, Resource Type, and Service across all.

## Adding a Recommendation

If you want to add a Custom Recommendation, select the Infrastructure that you want and the **Add Recommendation** button will become available at the top.

Clicking Add Recommendation with selected infrastructure resources will automatically link the infrastructure. The selected resource is referenced under the Infrastructure section in Custom Recommendation, and the related Segment is already pre-selected so the recommendation will go to the relative team.

We recommend making recommendations on a team's Primary Segment as that is used in reporting for Groups.

## Related Resources

* [Resource Recommendations - Overview](/help-center/user-guide/resource-recommendations)
* [Product Overview](/help-center/getting-started/product-overview)


# Resource Recommendations - Overview

Balancing team infrastructure actions such as rightsizing or refactoring changes against infrastructure commitment savings and long-term goals can be challenging. We built the Resource Recommendation engine to help with commitment-aware rightsizing as well as to provide the flexibility to track recommendations from a number of sources — AWS Compute Optimizer, other cloud providers, and internal tools for your company.

The system can recommend EC2 sizes, Unattached EBS volumes, and other non-commitment type optimizations.

## Setting Up Compute Optimizer

### AWS

Follow the setup instructions to enable Compute Optimizer. We pull the recommendations in daily, so you should see recommendations coming into your account within the next day.

### Azure and GCP

Contact Sales at <sales@archera.ai>.

## Custom Recommendations & Syncing with External Sources

Custom recommendations can be added manually or through our API. For API access contact <sales@archera.ai>.

You can also use the API to query Recommendations and send them to your preferred system.

You can filter specific Recommendations by Segment.

## Recommendations Overview

The overview provides a breakdown of recommendations by Provider/Source as well as top recommendations by Type. When new recommendations come in they are flagged as **New** and team members can mark the stages:

* **New**
* **Reviewed**
* **Completed**

Items that are marked as complete or reviewed will show up in the Events stream for team members to review.

## Recommendations Table

Recommendations are filterable by the Segment Selector at the top of the page. From there you can do additional filtering in the search for things such as:

* Region
* Type
* Resource Family

Any field that's available in the table should return those types of recommendations.

You can select a specific recommendation and — if there are multiple options — select an option for the team to take. Choice changes are tracked and you can add notes to the recommendation.

If, for example, you have EC2 recommendations around CPU and you are more interested in Network and Memory based recommendations, mark the recommendation as not relevant and leave a note. This acts as a feedback loop for the Archera team on the relevancy of the recommendations.

## Related Resources

* [Infrastructure History - Overview](/help-center/user-guide/infrastructure-history)
* [Product Overview](/help-center/getting-started/product-overview)


# Commitment Planner - Overview

The Commitment Planner is designed to provide an optimal mix of contracts based on your business requirements. Archera provides 3 out-of-the-box recommendations, but from there you can adjust and optimize however you like to fit your infrastructure and business needs.

## Top Things to Try

1. **Create and Save a Custom Plan** — Start from a Recommended Plan and customize it to your needs
2. **Add Notes to Your Plan** — Include questions or notes to help track history and rationale
3. **Share for Review** — Share the plan with colleagues or the Archera team for feedback and suggestions

Our team is always happy to review and provide guidance on your plans.

## Calculation Details

### Default Analysis

* Calculations use the last 30 days of data for default analysis
* For AWS: defaults to the last 30 days of Cost Explorer data unless you enable CUR in both AWS and Archera
* Custom plans can be adjusted to use less data for more granular analysis

### Service Coverage

* Default plans look for services with 80% or more uptime
* For more granular coverage, you can adjust a custom plan to use less time

## Segments Overview

Segments are bundles of infrastructure resources such as servers, databases, and other infrastructure. The portion of infrastructure resources that are coverable based on the segment are shown under Service Breakdown.

When you select a segment in the Commitment Planner, you'll get resources that are "Coverable," meaning you can purchase commitment contracts to get discounted pricing. Typical term lengths for these contracts are 1 or 3 years.

## Purchase Plans

Once you've selected your Segment, you can review Recommended Plans. Archera analyzes your current instances and commitments to determine what infrastructure can and should be covered by which permutations of available savings vehicles.

### Built-in Plans

**Flexibility Optimized**

* Least upfront spend
* Shorter term length commitments
* More Savings Plans vs Reserved Instances
* Best for segments going through change or with limited capital access

**Balanced**

* Middle ground between flexibility and savings
* Moderate upfront costs and term lengths
* Solid savings without overcommitting

**Savings Optimized**

* Larger upfront cost
* Longer term lengths
* Highest Net Savings Rates
* Best for stable, well-established infrastructure

You can click the dots to edit and save a Recommended Plan as a Custom Plan.

## Plan Summaries

Each plan includes a detailed line item summary breakdown. Most items can be hovered over to get further details.

### Coverage Section

The orange and green bar shows:

* Additional coverage being proposed in the plan
* Target coverage percentage

### Cost Preview

A graphical representation of monthly breakdown:

* **Dark Blue**: Native offerings from cloud providers
* **Orange**: Upfront costs (if any)
* **Light Blue**: Archera Guaranteed Commitments

### Plan Totals

Options to view:

* Monthly breakdowns
* Yearly totals
* Lifetime costs
* Raw Savings and Commitment dollar values

## Archera's Guaranteed Commitments

Archera's unique commitment offering provides additional options beyond native cloud provider offerings. These commitments offer superior flexibility and terms. See [What are Guaranteed Commitments?](/help-center/guaranteed-commitments/what-are-guaranteed-commitments) for more details.

## Adjusting Plans

You can verify contracts in any plan, make adjustments, and create your own Custom Plan:

1. Click the "View Details" button on any plan
2. Customize to your needs
3. Review and save your custom configuration

See [How to Create a Custom Purchase or Renewal Plan](/help-center/user-guide/how-to-create-custom-plan) for a step-by-step guide.

## Plan Details View

### Contracts Tab

Review contract groups and the resources they apply to. Click "Edit Reservation" to modify contract group settings.

### Monthly Costs

Displays:

* Total Upfront Cost
* Net Savings
* Commitment amounts

### Total Costs Graph

Shows cumulative total cost over time.

### Break Even Analysis

Displays the date when the cost breaks even and your company sees returns on savings.

## Related Resources

* [How to Create a Custom Purchase or Renewal Plan](/help-center/user-guide/how-to-create-custom-plan)
* [Commitment Inventory](/help-center/user-guide/commitment-inventory)
* [What is the lookback period inside commitment planner?](/help-center/user-guide/lookback-period)
* [What Contract Terms combinations are available for AWS Services?](/help-center/user-guide/contract-terms-aws)


# Commitment Inventory

Commitment Inventory allows you to manage existing commitments and plan for renewal. This tool provides visibility into your current cloud commitments and helps you make informed decisions about future renewals.

## Viewing Expiring Contracts

The interface displays a graph of expiring contracts over time. You can click on "Expiring Contracts" in the graph, and the related commitment entries will be selected and highlighted in the table below.

## Creating Renewal Plans

When you identify commitments that are approaching expiration:

1. Click on the commitment in the graph or table
2. Click "Create Renewal Plan"
3. Archera's system will provide you with three default renewal plans
4. You can also create custom renewal plans tailored to your specific needs

The renewal planning feature helps ensure you maintain optimal commitment coverage and maximize savings opportunities without gaps in your coverage.

## Related Resources

* [Commitment Planner - Overview](/help-center/user-guide/commitment-planner)
* [How to Create a Custom Purchase or Renewal Plan](/help-center/user-guide/how-to-create-custom-plan)
* [Billing and GRIs](/help-center/billing/billing-and-gris)


# Settings & Integrations - Section Overview

The Account Settings page allows you to change global settings for your Organization as well as your personal User settings.

## Available Settings

### Personal Account

Manage your individual user profile and preferences.

### Organization

Adjust organizational-level settings and configurations.

### Users

Manage team members and user access to your Archera account.

### Integrations

Connect external tools and services to enhance your Archera workflow.

### Segments

Configure segments for organizing and analyzing your cloud infrastructure.

### Messaging

Set up communication preferences and notifications.

### API Access

Manage API keys and credentials for programmatic access to Archera.

### Slack

Connect your Slack workspace for notifications and updates.

### CUR Definitions

Define and manage your Cost and Usage Report (CUR) settings.

### SSO

Configure Single Sign-On for streamlined authentication across your organization.

## Related Resources

* [How Do I Configure SSO for Azure AD](broken://pages/SQDVigV4D6KFVfIoH90v)
* [How and why do I connect my AWS Cost and Usage Report (CUR) to Archera?](/help-center/aws-onboarding/connect-cur)
* [Invite Users and Onboarding Troubleshooting](/help-center/user-guide/invite-users)


# How to Create a Custom Purchase or Renewal Plan

Creating a custom plan in Archera is your way of tailoring savings to fit your organization's exact infrastructure footprint. Whether you're building a Purchase Plan or a Renewal Plan, the process is nearly identical.

By default, Archera automatically generates three plan options for each segment: Recommended, Balanced, and High Savings. However, there are scenarios where creating a Custom Plan makes more sense, such as:

* Include or exclude specific savings vehicles
* Specify a particular lookback period
* Adjust or test different term lengths
* Explore a unique configuration tailored to your team's goals

## Creating Your Custom Plan

To create a Custom Plan, click the "Custom Plan" button or modify one of the existing default plans from the Commitment Planner section. You can also create a Renewal Plan from the Commitment Inventory page.

### Step 1: Choose Your Custom Plan Type

You'll see three options:

**Top-Down Plan** — Want to cover everything across your infrastructure? This pulls usage directly from your CUR data and gives a holistic, org-wide view.

**Infrastructure Plan** — Want to zoom in on specific workloads? Use the search bar to filter by instance type, tags, or resource name, then select what you want to include.

**Renewal Plan** — Access this from either the Commitment Planner or Commitment Inventory page. Perfect for tracking and renewing upcoming expiring commitments.

### Step 2: Name Your Plan

Start by giving your plan a descriptive name. Think about who created it, what it's for, and when you created it. Example: `RDF 30 Day GRI (RDS Only)`

### Step 3: Select Reservable Infrastructure

Head to the Reservable Infrastructure section. Use the search bar to find and select the commitments you want included by name, instance type, or tags. Anything you leave unchecked will be excluded.

### Step 4: Adjust the Lookback Period

The system default is 1 day, but you can customize this. Click "Different Range" to slide the lookback window to something that better fits your usage patterns (like 7, 14, or 30 days).

### Step 5: Choose Contract Types

By default, all contract types are selected. If you want to narrow your scope (e.g., Standard RIs, Compute Savings Plans, Sagemaker Contracts only), deselect the rest.

### Step 6: Choose Contract Terms

Select the terms you need:

* 30-day or 1-year GRIs
* 1-year or 3-year AWS Reserved Instances

Archera GRIs offer more flexibility with shorter terms, easier modifications, and no lock-in.

### Step 7: Select Upfront Costs

Choose your preferred upfront structure:

* No Upfront
* Partial Upfront
* All Upfront

Archera's Recommended and Balanced Plans default to No Upfront, which means you get savings without tying up capital.

### Step 8: Optimize for Upfront Spend

Archera visualizes this on a Pareto Frontier, automatically finding the sweet spot where adding more spend doesn't meaningfully increase savings. You can also override this and pick a flat upfront option if preferred.

### Step 9: Review and Apply

Click the purple **Submit** button. This creates and saves your plan in the Draft Plans section of the Commitment Planner but does not trigger a purchase.

Once savings calculations complete, review:

* Covered services
* Savings projections
* Contract details

When you're ready, click "Apply Plan" from either the Draft Plans tab or within the plan itself.

## Fine-Tuning Your Plan

Click "View Details" to explore per-line-item breakdowns including contract terms, cost type, and coverage by resource.

For additional questions, reach out to <solutions@archera.ai>.

## Related Resources

* [Commitment Planner - Overview](/help-center/user-guide/commitment-planner)
* [Commitment Inventory](/help-center/user-guide/commitment-inventory)
* [What is the lookback period inside commitment planner?](/help-center/user-guide/lookback-period)


# How Does Archera Calculate Commitment Coverage

## Does Archera define commitment coverage differently from AWS?

Yes — Archera defines commitment coverage a bit differently from AWS to make the evaluation process for Commitment Strategies as intuitive as possible.

## The Difference

**AWS, Azure and Google Cloud** define Commitment coverage as the total number of On-demand Running Hours being covered by Commitments.

**Archera** defines Commitment coverage as the total On-demand Spend in $ being covered by Commitments.

This makes it more clear to customers what costs are being committed to, instead of resource hours that can be billed at wildly different rates.

## Example Scenario

Imagine you are running:

* A t3 (cheap compute VM) — $5 per day
* A p4 (expensive GPU VM) — $770 per day
* **Total:** $775 per day with 0% coverage

If you buy a commitment for the t3:

**According to AWS:** You increase coverage to 50% but are still paying $772 a day on-demand.

**According to Archera:** You increase coverage to only 1% since the majority of your $772 a day spend is on-demand.

## Why This Matters

The Archera approach gives a consistent metric to compare between Commitment strategies and also helps avoid strange cases where plans with much lower coverage yield far higher savings compared to plans covering many more cheaper machines.

## Related Resources

* [Commitment Planner - Overview](/help-center/user-guide/commitment-planner)
* [How to Create a Custom Purchase or Renewal Plan](/help-center/user-guide/how-to-create-custom-plan)


# How Does Commitment Discount Attribution Work

## Attribution Concept

This touches on a concept called "Attribution" in Archera, which handles which RIs & SPs are applied to which resources within your account, along with associated costs & savings.

## AWS Default Attribution Strategy

AWS has a default attribution strategy where all commitments are applied against all resources based on what gets the highest discount, and for resources that get the same discount, attribution is handled in an arbitrary manner.

This behavior applies both to:

* Commitments purchased natively through AWS Cost Explorer
* Commitments purchased through Archera (even if they were purchased for a particular segment)

## Archera's Default Attribution

Archera, by default, employs the AWS default attribution strategy. We do this because the default attribution strategy aligns with what will be shown on your AWS bill and usage report.

Using a different attribution strategy could lead to discrepancies between AWS and Archera in terms of the precise cost of each resource.

## Custom Attribution for Enterprise Customers

For customers seeking an alternative chargeback model distinct from the AWS default — featuring a custom attribution strategy — we offer the capability to support custom attributions for any Reserved Instance (RI) or Savings Plan (SP) through our Custom Reporting Functionality.

This feature is employed by our enterprise customers for:

* In-depth analysis of COGS
* Margin analysis
* Business Unit (BU) showback/chargeback
* Other customized functionalities

## Related Resources

* [Billing and GRIs](/help-center/billing/billing-and-gris)
* [How Does Commitment Discount Attribution Work in Archera?](/help-center/billing/discount-attribution)
* [Product Overview](/help-center/getting-started/product-overview)


# Invite Users and Onboarding Troubleshooting

## Inviting Users to Your Archera Organization

To invite users to your Archera account, follow these steps:

1. Click on the selection arrow next to your organization name
2. Click on "Organization Settings"
3. Click on "Users"
4. Click on "Invite Members"
5. Enter the email address for the user you wish to invite
6. Click "Submit"

## Onboarding Troubleshooting

If you are an invited user and are stuck in onboarding or your organization looks incorrect:

### Verify the Invite

Ask the sender or admin of the Archera organization if the invite has been sent. You can check the settings page to confirm.

### Email Address Issues

If the invite was sent to an alias or secondary email address instead of your primary account email, the connection may not work properly. In this case:

* Request a new invite to your primary email address
* Do not attempt to sign in with another email address, as this will not link you to the account
* If you've already created an account with the wrong email, contact support to remove the incorrect account

## Related Resources

* [How do I remove or add a user to my Archera account?](/help-center/user-guide/add-remove-users)
* [Settings & Integrations - Section Overview](/help-center/user-guide/settings-integrations)


# How Do I Remove or Add a User?

To remove or invite new users to your Archera account, navigate to the arrow in the top left next to your org name. Then click on "Organization Settings" followed by clicking on the "Users" section.

## Adding Users

To add users, click the **"Invite Members"** button at the top of the page to invite a new user via their email and assign a specific role.

## Managing and Removing Users

To manage or remove specific users, you can click the remove button to revoke access or change the user's role in the table.

## Restricting Cloud Access

If you would like to opt-out of giving your cloud account representatives or MSP/Reseller/Cloud-Consultants access to your environment, you can restrict their role or remove them from your account entirely via this page.

## Related Resources

* [Invite Users and Onboarding Troubleshooting](/help-center/user-guide/invite-users)
* [Settings & Integrations - Section Overview](/help-center/user-guide/settings-integrations)


# What is the Lookback Period?

The lookback period is a critical parameter when creating custom commitment plans in Archera. It determines how far back in your usage history Archera looks when calculating recommendations.

## Why the Lookback Period Matters

If your organization experiences temporary usage spikes or drops (for example, a recent spike in temporary usage or a drop during a weekend), the default commitment plans could be skewed by these recent fluctuations. By adjusting the lookback period to a longer timeframe, you get recommendations that are more robust to these temporary variations.

## How to Set the Lookback Period

1. Navigate to the **Commitment Planner** from the left-hand navigation pane
2. Click the purple **"Create Custom Plan"** button on the right-hand side of the page
3. Select the **"Top Down"** plan option from the menu

## Adjusting the Lookback Period

By default, the commitment planner has a lookback period of **7 days**. To lengthen this period:

1. Click on **"Different Range"** at the bottom right of the configuration menu
2. Use the slider provided to select your desired date range
3. Typical examples include 30, 60, or 90 days

## Completing Your Plan

Once you've set your preferred lookback period:

1. Configure any other desired options for your commitment plan
2. Click **"Submit"**
3. Wait for the plan to calculate

## Benefits of Longer Lookback Periods

Setting a longer lookback period allows Archera to acquire a better usage baseline to cover with the recommended commitments. This results in more accurate and reliable recommendations for your cloud infrastructure needs.

## Related Resources

* [Commitment Planner - Overview](/help-center/user-guide/commitment-planner)
* [How to Create a Custom Purchase or Renewal Plan](/help-center/user-guide/how-to-create-custom-plan)
* [How Does Archera Calculate Commitment Coverage](/help-center/user-guide/commitment-coverage)


# What Contract Terms Are Available for AWS?

When using the Archera Commitment Planner to create a custom plan, you have the opportunity to customize the "Contract Terms." These terms are used by Archera to calculate your plan and include:

* Commitment length
* Upfront cost options

These apply to both Archera Guaranteed Commitments (GRIs/GSPs) and AWS Native Commitments.

## Available Contract Term Combinations by Service

Archera provides specific contract term combinations for each AWS service. The available combinations vary depending on the service:

### Supported AWS Services

* Amazon EC2
* Amazon EKS
* Amazon RDS
* Amazon ElastiCache
* Amazon OpenSearch
* Amazon Redshift
* AWS Lambda
* Amazon ECS
* AWS Fargate
* Amazon SageMaker

## Archera Guaranteed Savings Plans

If you're interested in more broadly leveraging Archera Guaranteed Savings Plans, check the available contract term combinations which may differ from individual service offerings.

### Amazon Compute Savings Plans (CSP)

Compute Savings Plans offer flexible contract terms across compute services.

## Custom Contract Terms

If you're interested in a custom contract term length not listed (such as a 90-day GRI, 6-month GRI, or other custom durations), please reach out to the Archera team with your specific requirements. We can work with you to find solutions tailored to your needs.

## Related Resources

* [Commitment Planner - Overview](/help-center/user-guide/commitment-planner)
* [What are Guaranteed Commitments?](/help-center/guaranteed-commitments/what-are-guaranteed-commitments)
* [What are Guaranteed Commitments premiums and term lengths?](/help-center/guaranteed-commitments/premiums-and-terms)


# Archera's Savings Options

At Archera, we understand that cloud savings aren't one-size-fits-all. Every business has unique needs when it comes to managing cloud costs. That's why we offer three carefully designed, out-of-the-box savings plans.

## The Three Core Plans

### 1. Recommended Plan: Flexible Savings, Minimal Commitment

Perfect if you're new to cloud cost optimization or your workloads change frequently.

**Commitment Length:** 30 days — no long-term commitment anxiety.

**Type of Commitments:** 30-day GRIs (Guaranteed Reserved Instances)

**Why You'll Love It:** It's our most flexible option, offering immediate savings without locking you in. Perfect for dynamic environments or those just starting their cloud savings journey.

**Use Cases:**

* Over-provisioned infrastructure needing cost trimming
* Right-sizing tests without long-term commitment
* Startups with uncertain growth
* Businesses navigating unpredictability
* Teams averse to technical changes
* Infrastructure modernization efforts

### 2. Balanced Plan: The Goldilocks Option

Strikes harmony between flexibility and savings.

**Commitment Length:** 1 year

**Type of Commitments:** Primarily 1-year GRIs and sometimes 1-year standard RIs

**Why You'll Love It:** Dependable and great for predictable workloads. You'll enjoy steady savings while keeping some flexibility for adjustments.

**Key Advantage:** For non-RDS infrastructure, Archera's 1-year GRIs are exceptional value, often outperforming standard 1-year native instances.

**Use Cases:**

* Stable, predictable workloads
* Cost-conscious growth environments
* Non-RDS infrastructure optimization
* Teams with clear 1-year roadmaps

### 3. High Savings Plan: Maximum Savings

For those who want to maximize every dollar saved.

**Commitment Length:** 1 year, with optional 3-year commitments for deeper discounts

**Type of Commitments:** Heavy on 1-year GRIs, plus 3-year commitments for maximum savings

**Why You'll Love It:** If you have stable, predictable workloads, this plan delivers maximum savings.

**Use Cases:**

* Stable, predictable workloads
* Organizations ready for long-term commitment
* Established infrastructure with mature systems
* Heavy cloud users with consistent workloads

## Custom Savings Plans

Not finding your perfect match? Archera can create custom savings plans tailored to your specific needs:

* **Configurable Term Lengths:** You decide how long you want to commit
* **Focused Savings:** Target specific areas of your cloud infrastructure
* **Customized Approach:** Create the perfect savings recipe for your business

## How to Choose

Still unsure which plan to pick? Our team of cloud cost optimization experts is here to help. We'll analyze your usage, discuss your needs, and recommend the best plan to keep your savings significant and your commitments stress-free. Reach out to <solutions@archera.ai>.

## Related Resources

* [Commitment Planner - Overview](/help-center/user-guide/commitment-planner)
* [What are Guaranteed Commitments?](/help-center/guaranteed-commitments/what-are-guaranteed-commitments)
* [Recommended Plan: Flexible Savings, Minimal Commitment](/help-center/user-guide/recommended-plan)


# Recommended Plan: Flexible Savings, Minimal Commitment

If you're new to cloud cost optimization or your workloads change frequently, the Recommended Plan is the perfect place to start.

## Plan Details

**Commitment Length:** Just 30 days — no long-term commitment anxiety.

**Type of Commitments:** 30-day GRIs (Guaranteed Reserved Instances)

**Why You'll Love It:** It's our most flexible option, offering immediate savings without locking you in for the long haul. Perfect for dynamic environments or those just starting their cloud savings journey.

Think of this plan as the appetizer — it's light, satisfying, and lets you test the waters. It offers the freedom to adapt quickly while still unlocking immediate savings.

## Ideal Use Cases

### Over-provisioned Infrastructure

Trim costs while figuring out what you actually need.

### Right-Sizing Needs

Test optimizations without committing long-term.

### Startups

Great for businesses with uncertain growth and evolving needs.

### No Business Certainty

Stay agile while navigating unpredictability.

### Adverse to Tech Changes

Save without overhauling your setup.

### Modernizing Infrastructure

Dip your toes into optimization as you upgrade.

## Benefits at a Glance

* Immediate savings without long-term lock-in
* Flexibility to adjust as needs change
* Perfect entry point for cloud cost optimization
* Ideal for unpredictable or dynamic workloads
* Easy to upgrade to more aggressive plans later

## Related Resources

* [Archera's Savings Options](/help-center/user-guide/savings-options)
* [Commitment Planner - Overview](/help-center/user-guide/commitment-planner)
* [What are Guaranteed Commitments?](/help-center/guaranteed-commitments/what-are-guaranteed-commitments)


# Why is my Dashboard a Day or Two Behind?

## AWS

AWS does not ensure the completeness or accuracy of the previous day's Cost and Usage until after that day has concluded. Our chosen point in time (approximately two days afterwards) guarantees that the data will be fully comprehensive, regardless of when AWS finalizes the CUR data for that specific day.

To clarify, data from November 1 will only become visible once November 3 has begun.

## Google Cloud & Azure

Google Cloud and Azure are usually no more than 24 hours behind based on when our systems pull and process the billing data.

## Related Resources

* [How Does Commitment Discount Attribution Work in Archera?](/help-center/billing/discount-attribution)
* [Could Archera Change or Impact My Application?](/help-center/faq/could-impact-application)
* [How Do I Audit Archera?](/help-center/faq/audit)


# Guaranteed Commitments

Everything you need to know about Archera's insurance-backed cloud commitment products — GRIs (Guaranteed Reserved Instances), GSPs (Guaranteed Savings Plans), and GCUDs (Guaranteed Committed Use Discounts).

## Articles in This Section

* [What are Guaranteed Commitments?](/help-center/guaranteed-commitments/what-are-guaranteed-commitments)
* [What are Guaranteed Commitment Premiums and Term Lengths?](/help-center/guaranteed-commitments/premiums-and-terms)
* [What are Guaranteed Commitment Allowances?](/help-center/guaranteed-commitments/allowances)
* [How Can I Raise My Guaranteed Commitment Allowances?](/help-center/guaranteed-commitments/raise-allowances)
* [Why Are Allowances for Certain Guaranteed Commitment Types Lower?](/help-center/guaranteed-commitments/allowances-lower-types)
* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)
* [Do Guaranteed Commitments Work with AWS GovCloud?](/help-center/guaranteed-commitments/govcloud)
* [How do Guaranteed Commitments Work for Instances with Low Capacity like GPUs?](/help-center/guaranteed-commitments/low-capacity-instances)
* [What are My Billing Options if I'm Still on AWS Credits?](/help-center/guaranteed-commitments/billing-options-aws-credits)
* [Do You Have 3rd-Party Insurance?](/help-center/guaranteed-commitments/third-party-insurance)
* [How Does the AWS RI Marketplace Restriction Affect Archera?](/help-center/guaranteed-commitments/ri-marketplace)
* [How to Enable EC2 RI Marketplace](/help-center/guaranteed-commitments/enable-ri-marketplace)
* [How do Rebate Insured Commitments Work?](/help-center/guaranteed-commitments/rebate-insured-commitments)
* [How Can I Change the Term Length of My Guaranteed Commitment?](/help-center/guaranteed-commitments/change-term-length)
* [How does the Buyback/Rebate Guarantee Mechanic Work?](/help-center/guaranteed-commitments/buyback-rebate-mechanic)


# What are Guaranteed Commitments?

Archera Guaranteed Commitments — including Guaranteed Reserved Instances (GRIs), Guaranteed Committed Use Discounts (GCUDs), and Guaranteed Savings Plans (GSPs) — are normal 1 or 3-year AWS, Google Cloud, or Azure Reserved Instances, Committed Use Discounts, or Savings Plans where Archera guarantees to cover the cost of any losses due to overcommitment at any point after a configurable term length. This guarantee is delivered through either the resale of the commitment or rebating of its un-utilized costs.

Guaranteed Commitment term lengths can be as short as **30 days** and as long as **1 year**. Archera Guaranteed Commitments have a premium associated with them that is reflected in the net savings rate of each Guaranteed Commitment. Longer term lengths have higher net savings rates. These percentages are variable due to a number of factors controlled by AWS, Azure, and Google Cloud — including instance type, region, etc.

Savings rates can often be better than those shown below, subject to underwriting upon connecting Archera to your Cloud Billing.

| Guaranteed Commitment Term Length | Net Savings Rate |
| --------------------------------- | ---------------- |
| 30 days                           | \~29%            |
| 1 year                            | \~46%            |

## Related Resources

* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)
* [What are Guaranteed Commitments premiums and term lengths?](/help-center/guaranteed-commitments/premiums-and-terms)
* [What are Guaranteed Commitment allowances?](/help-center/guaranteed-commitments/allowances)
* [Do Guaranteed Commitments work with AWS GovCloud?](/help-center/guaranteed-commitments/govcloud)
* [Do you have 3rd-party insurance?](/help-center/guaranteed-commitments/third-party-insurance)


# Premiums and Term Lengths

Archera Guaranteed Commitments have two variable components — a **term length** and a **premium** — that are inversely related. The longer the term length, the lower the premium, and vice versa: shorter term lengths have higher premiums.

The **Guaranteed Commitment Premium** is the difference between the standard Savings Rate of the underlying standard RI/SP and the net savings rate of the Guaranteed Commitment. You can see the Guaranteed Commitment premiums on your invoice page.

Keep in mind, Guaranteed Commitment premiums are only assessed on **realized** savings. Meaning — if for some reason you can't use the underlying infrastructure, you aren't responsible for the premium.

## Related Resources

* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)
* [What are Guaranteed Commitment allowances?](/help-center/guaranteed-commitments/allowances)
* [What are my Guaranteed Commitment billing options if I'm still on AWS Credits?](/help-center/guaranteed-commitments/billing-options-aws-credits)


# What are Guaranteed Commitment Allowances?

Since Archera Guaranteed Commitments are a mechanism for our customers to offload some of their commitment risk to us, we can only offer a limited amount of any given Guaranteed Commitment type to customers to balance our own internal risk.

Allowances are set dynamically based on market liquidity by Archera's underwriting algorithm, and over time allowances do grow.

Allowances are automatically reflected by the Archera Purchase/Renewal planners, so any remaining balance will automatically be utilized if there is an opportunity to do so.

For further details please contact us at <support@archera.ai>.

## Related Resources

* [Why Are Allowances for Certain Guaranteed Commitment Types Lower?](/help-center/guaranteed-commitments/allowances-lower-types)
* [How can I raise my Guaranteed Commitment Allowances?](/help-center/guaranteed-commitments/raise-allowances)
* [What are Guaranteed Commitments premiums and term lengths?](/help-center/guaranteed-commitments/premiums-and-terms)


# How Can I Raise My Allowances?

Guaranteed Commitment Allowances are a way for Archera to manage the risk associated with allowing customers to offload some of their commitment risk to us.

See [What are Guaranteed Commitment allowances?](/help-center/guaranteed-commitments/allowances) for background.

These allowances are mainly set by Archera's underwriting algorithm based on market liquidity for different commitment types. However, part of the total Guaranteed Commitment allowance a given customer has access to is based on the **volume and diversity** of Guaranteed Commitments the customer has purchased.

**This means that customers who have purchased more Guaranteed Commitments across different service types (e.g. EC2, RDS, Redshift, etc.) as well as different instance families within those services get access to higher overall Guaranteed Commitment allowances.**

If you are interested in learning more, please contact us at <support@archera.ai>.

## Related Resources

* [What are Guaranteed Commitment allowances?](/help-center/guaranteed-commitments/allowances)
* [Why Are Allowances for Certain Guaranteed Commitment Types Lower?](/help-center/guaranteed-commitments/allowances-lower-types)


# Why Are Allowances for Certain Types Lower?

Archera's Guaranteed Commitment allowances & premiums are set primarily based on risk as assessed by Archera's underwriting algorithm. This means for certain instance types, services, and regions the number of Guaranteed Commitments available to purchase from Archera can be much lower than for others. This is based dynamically on the amount of demand for the commitments in the marketplaces Archera has access to.

For example, Archera tends to offer the highest Guaranteed Commitment allowances for common EC2 instance types in the most popular regions, given these are the most popular and in-demand commitment types. However, for less popular RDS instance types — which are not as in-demand as EC2 instances — the allowance can be much lower and average premiums higher.

There are also specific ways individual customers can increase their overall allowances as outlined in [How can I raise my Guaranteed Commitment Allowances?](/help-center/guaranteed-commitments/raise-allowances).

## Related Resources

* [What are Guaranteed Commitment allowances?](/help-center/guaranteed-commitments/allowances)
* [How can I raise my Guaranteed Commitment Allowances?](/help-center/guaranteed-commitments/raise-allowances)


# How Does Guaranteed Commitment Pricing Work?

Guaranteed Reserved Instances (GRI), Savings Plans (GSP), and Committed Use Discounts (GCUD) are unique, insurance-backed cloud commitment options offered by Archera.

Guaranteed Commitments charge a small monthly risk **premium only if the underlying commitment delivers savings for the customer** — working out to a small percentage of the savings achieved by the Guaranteed Commitment for the customer.

In exchange for this, customers get the option to **either get a direct rebate for any un-utilized committed value or entirely sell back the remainder of the up to 3-year commitment to Archera at any time after a minimum term length** (either 30 days or 1 year).

This means when a customer commits to an Archera Guaranteed Commitment there will be two separate charges:

1. One for the underlying native 1 or 3-year CUD, RI, or SP billed by the cloud provider
2. One charge via the cloud marketplace from Archera for the Guaranteed Commitment **premium**

## Term Lengths

We have two primary Guaranteed Commitment **term lengths** — 30 days and 1 year — that customers can choose between when purchasing a Guaranteed Commitment, each with a different monthly premium based on the risk assumed by Archera. Premiums may also vary slightly based on instance type, region, etc.

## Related Resources

* [What are Guaranteed Commitments premiums and term lengths?](/help-center/guaranteed-commitments/premiums-and-terms)
* [What are Guaranteed Commitment allowances?](/help-center/guaranteed-commitments/allowances)
* [What are my Guaranteed Commitment billing options if I'm still on AWS Credits?](/help-center/guaranteed-commitments/billing-options-aws-credits)
* [Billing and GRIs](/help-center/billing/billing-and-gris)


# Do Guaranteed Commitments Work with AWS GovCloud?

Yes! Guaranteed Reserved Instances (GRIs) and Guaranteed Savings Plans (GSPs), with flexible term lengths and commitments as short as 30 days, are fully supported on AWS GovCloud.

Because Archera's Guarantee for GRIs is structured as a direct rebate, it doesn't rely on services only available in AWS commercial cloud (such as the EC2 Standard RI marketplace), and so is fully supported on AWS GovCloud.

## Related Resources

* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)
* [Do I Need to Grant Archera Access to my GovCloud Account?](/help-center/sign-in-and-security/govcloud-access)
* [What are Guaranteed Commitments premiums and term lengths?](/help-center/guaranteed-commitments/premiums-and-terms)


# Low Capacity Instances (GPUs)

## On AWS

There are multiple types of commitments that AWS offers, some of which — like Zonal Standard Reserved Instances (RIs) — come bundled with a capacity reservation to ensure access to the underlying machine being covered. See [AWS capacity reservations documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-capacity-reservations.html) for more details.

By default, Archera Guaranteed Commitments are created from Regional Standard RIs or Savings Plans, which don't come with a capacity reservation; however, they can synergize with an existing capacity reservation to provide a billing discount.

In certain circumstances — particularly with machines like GPUs that have low-capacity-availability — Archera supports creating Guaranteed RIs (GRIs) from **Zonal Standard RIs**, which do come with a capacity reservation and can give customers the peace of mind that they will always have access to spin up the machine they are committed to.

Please note that this is **not the default GRI option** and you will have to contact us in order to make use of this option.

If you are interested in using Zonal GRIs with a capacity reservation, please contact <support@archera.ai> to learn more.

## Related Resources

* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)
* [What are Guaranteed Commitments?](/help-center/guaranteed-commitments/what-are-guaranteed-commitments)
* [Does Archera support On Capacity Demand Reservations? (OCDR)](/help-center/faq/ocdr)


# Billing Options if Still on AWS Credits

## Options to Avoid Paying Guaranteed Commitment Costs Out of Pocket

Some AWS customers take advantage of various credit programs from AWS. These credits allow for "free" usage of AWS tools and services. Since Archera uses the AWS Marketplace to bill customers, some customers can find themselves in a situation where they receive an unexpected bill from AWS. This is because in some cases AWS Marketplace transactions are not eligible for certain credit programs (contact your AWS representative for clarification, and [read through the AWS Credits Page](https://aws.amazon.com/awscredits/) for further details).

To support these customers, Archera offers the following option:

If you're fully on credits and those credits don't apply to AWS Marketplace transactions — we will not charge you until you are off credits. In this case we're essentially a "free" way to extend your credits. However, we will track your GRI premiums over time. Once you are off credits we can charge your premiums, either lump sum or on an ongoing amortized basis over the course of the subsequent months.

If you want to resell or receive a rebate for Guaranteed Commitments while still on credits, you'll still need to settle your premiums with us via Marketplace in order to do so.

## Related Resources

* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)
* [How Do I Apply AWS Credits to My Account?](/help-center/billing/aws-credits)
* [What are Guaranteed Commitments premiums and term lengths?](/help-center/guaranteed-commitments/premiums-and-terms)


# 3rd-Party Insurance

## How can I be sure my Guaranteed Commitments will be honored even if something happens to Archera?

We have specialized liability insurance capable of covering any catastrophic outcome — i.e., rebating or buying back all outstanding Guaranteed Commitment obligations if something unexpected happens to Archera.

Under Archera's Insured Commitment model, customers are always contractually made whole via a direct rebate in any case where a Guaranteed Commitment cannot be resold from a properly configured account. This is via a specific policy covering our Guaranteed Commitment program, and the obligation to maintain this coverage is referenced both in our click-through Terms of Service as well as our Master Services Agreement.

For any significant Guaranteed Commitment purchasers, we can provide additional documentation upon request.

## Related Resources

* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)
* [What are Guaranteed Commitments?](/help-center/guaranteed-commitments/what-are-guaranteed-commitments)


# How Does the AWS RI Marketplace Restriction Affect Archera?

## Does the 2023 AWS announcement on discounted RIs being listed in the EC2 Standard RI marketplace affect Archera customers?

Archera is not a Reseller or Distributor and doesn't rely on selling discounted EC2 RIs, which are the ones impacted by this change (e.g. ones acquired under volume discounts).

Since Archera is an insured commitment model (with actual insurance backing each commitment buy-back or utilization guarantee), we have the ability to rebate customers for any underutilized commitment that can't be resold — so the economics of any Guaranteed EC2 Standard RI remain the same to our customers regardless of resell-ability.

Additionally, Archera allows customers to buy and insure all commitment types, not just EC2 Standard RIs — so customers using Guaranteed Savings Plans, Convertible Reserved Instances, or other instruments would not be affected.

Finally, Archera's insured commitment model allows us to provide customers who may have these non-transactable RIs in their account the ability to add insurance on to them and de-risk them being underutilized, even without the ability to resell in the AWS EC2 Standard RI Marketplace.

## Related Resources

* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)
* [How to Enable EC2 RI Marketplace](/help-center/guaranteed-commitments/enable-ri-marketplace)
* [Do you have 3rd-party insurance?](/help-center/guaranteed-commitments/third-party-insurance)


# How to Enable EC2 RI Marketplace

To sell back Resale Guaranteed EC2 RIs, you will need to [Activate the EC2 RI Marketplace](https://aws.amazon.com/ec2/purchasing-options/reserved-instances/marketplace/) as the Root User in your AWS Management Account.

## Requirements

* The ability to login as the **Root User** of your AWS management account
* A business or individual bank account
* The business or individual tax identification number

## Steps

### 1. Register business

Navigate to the [EC2 RI Marketplace seller registration walkthrough](https://portal.aws.amazon.com/ec2/ri/seller_registration) and log in as the **Root User** (not IAM user) of your AWS Account.

Enter your business/individual name and click "Continue."

### 2. Add bank account

Enter your bank account information.

### 3. Add Tax Profile

Enter your tax profile information.

### 4. Complete Tax Interview

Complete the tax interview.

### 5. Verify activation

Wait a few business days for verification to complete.

## Related Resources

* [How Does the AWS Restriction on Selling Discounted EC2 RIs Affect Archera?](/help-center/guaranteed-commitments/ri-marketplace)
* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)


# How do Rebate Insured Commitments Work?

## What are Rebate Guaranteed Commitments?

Rebate Guaranteed Commitments are an opt-in feature for AWS customers that provides an alternative way to honor the Guarantee of Archera's Guaranteed Commitments. Azure customers use Rebate Insured Commitments by default.

Instead of giving back unused commitments through the Commitment Buyback page, Rebate Guaranteed Commitments stay in the customer's account. In the event of underutilization — after the initial lock-in period (30 days or 1 year) — Archera will automatically send a cash rebate to the customer for any net negative savings from the commitment.

This rebate can be used to:

* Offset other GRI premiums
* Be withdrawn to a bank account via ACH transfer (configured in the Payment Planner page)

## How to Set Up Rebate Guaranteed Commitments (AWS)

Navigate to the **Payment Planner** page and click **"Add Payout Account"** to add your preferred bank account. At the end of each month, if there were underutilized Guaranteed Commitments, you will automatically see that cost rebated into this page, ready to be withdrawn or put toward other Guaranteed Commitment premiums.

## How do I know if I have Rebate Guaranteed Commitments?

Rebate Guaranteed Commitments are tagged in the **Commitment Inventory** page with the label **"Rebating."**

## How do I opt-in?

For AWS customers, Rebate Guaranteed Commitments are not enabled on all services by default. To convert any Guaranteed Commitment to a Rebate Guaranteed Commitment:

* Reach out to <support@archera.ai>
* Chat with our team via in-app chat
* Schedule a free call with our Customer Success team

## Related Resources

* [How does the Buyback/Rebate Guarantee Mechanic Work?](/help-center/guaranteed-commitments/buyback-rebate-mechanic)
* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)
* [How to Enable EC2 RI Marketplace](/help-center/guaranteed-commitments/enable-ri-marketplace)


# How Can I Change My Term Length?

If you have an existing Guaranteed Commitment with a 30-day term and are confident in your workload's stability, you can convert it to a 1-year term to significantly reduce your monthly premium and increase your net savings.

## Why Convert to a Longer Term?

Longer term lengths result in lower premiums and higher net savings rates. This is because Archera assumes less risk with a longer commitment period, allowing us to pass those savings on to you.

For example, a commitment generating $980 in monthly savings at the 30-day term could generate approximately $1,471 in monthly savings at the 1-year term.

## How to Request a Term Change

Contact your Archera account team directly, via in-app chat, or via <support@archera.ai> with the following information:

**Customer Account Name:** Your full account name as it appears in Archera (e.g., "Company Name c/o Partner Name")

**Commitment IDs:** The specific commitments you want to convert. You can find the Commitment ID by:

1. Navigating to your Commitment Inventory
2. Clicking on the commitment row
3. Viewing the Commitment ID in the popup tooltip or Commitment Details page

## Important Considerations

**One-time conversion:** Converting from 30-day to 1-year is a one-time event. Once converted, the commitment cannot be changed back to a 30-day term.

**Lock-in period resets:** When you convert a commitment to a 1-year term, the 1-year lock-in period applies from the conversion date. This means that even if your 30-day commitment was already unlocked, it will return to "Locked" status until it reaches the 1-year anniversary of the conversion.

**Moneyback guarantee still applies:** After the 1-year lock-in period, Archera's moneyback guarantee continues to protect you. You can resell the commitment or receive rebates for any underutilization for the remainder of the underlying 3-year commitment term.

## When Should You Convert?

Consider converting to a 1-year term when:

* You have stable, predictable infrastructure with consistent usage patterns
* Your workload has been running successfully for several weeks or months
* You don't anticipate major architectural changes in the next 12 months
* You want to maximize your savings rate while maintaining flexibility after the initial year

If you're uncertain about your infrastructure needs, the 30-day term provides maximum flexibility with the ability to return commitments after just 30 days.

## Related Resources

* [What are Guaranteed Commitments?](/help-center/guaranteed-commitments/what-are-guaranteed-commitments)
* [What are Guaranteed Commitments premiums and term lengths?](/help-center/guaranteed-commitments/premiums-and-terms)
* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)


# How does the Buyback/Rebate Guarantee Mechanic Work?

The "moneyback guarantee" is a cornerstone of Archera's risk-free value proposition. There are three mechanisms through which Archera can honor the guarantee:

## The Three Guarantee Mechanisms

### 1. EC2 RI Marketplace

Archera acts as a market maker using the AWS EC2 RI marketplace. This enables the buyback of unused Standard Reserved Instances by selling them on the marketplace. **This mechanism is only available on AWS.**

### 2. Billing Transfer

For an insured commitment isolated to a single account or project with no running infrastructure, you can transfer the remaining payment obligation to Archera directly.

### 3. Rebate

This can be opted into for any insured commitment. Archera will purchase commitments on behalf of the customer, and if those commitments do not net the customer savings, Archera will rebate them the cost of the commitment less any negative savings (effectively the unused portion of the commitment cost). **Rebates are done automatically.**

## Automation

Buybacks can be automated by the customer based on:

* A lookback period (days/weeks/quarters)
* A dollar threshold of unused commitment

Automation applies to mechanisms 1 and 2. Rebates (mechanism 3) are done automatically regardless.

**Important:** If a customer using mechanism 1 or 2 does not have automation enabled, they run the risk of having commitments that do not save them any money — and cost them money — in the event they completely move away from the underlying resources or services.

## Review Process

There is often a review process for buybacks and commitment plan purchases, with up to a **5 business day SLA** for execution.

## Related Resources

* [How do Rebate Insured Commitments work?](/help-center/guaranteed-commitments/rebate-insured-commitments)
* [How to Enable EC2 RI Marketplace](/help-center/guaranteed-commitments/enable-ri-marketplace)
* [How Does Guaranteed Commitment Pricing Work?](/help-center/guaranteed-commitments/pricing)


# Commitment Automation

How commitment laddering, convertible RI exchange, and insurance-backed management compare — and why Archera includes automation tools that others charge for.

Cloud commitments — Reserved Instances, Savings Plans, Committed Use Discounts — deliver the largest rate discounts available on AWS, Azure, and GCP. The tradeoff is that purchasing them requires predicting your infrastructure needs over a 1–3 year window. Getting that prediction wrong has real financial consequences.

A category of tools emerged specifically to reduce this risk through automation. They solve two core problems:

* **Commitment laddering**: staggering commitment purchases across time so expirations are spread and you can continuously adjust your coverage as needs change
* **Convertible RI exchange**: automatically exchanging Convertible Reserved Instances as your instance mix evolves, so your commitments stay aligned with your actual workload

Archera includes both of these capabilities at no additional charge. But the platform also goes further — Archera underwrites your commitments against underutilization, which is something automation software alone structurally cannot provide.

***

* [What is Commitment Automation?](/help-center/commitment-automation/commitment-automation-explained) — How laddering and convertible exchange work, why a whole vendor category was built around them, and what Archera includes for free
* [Software-Only vs. Insurance-Backed Commitment Management](/help-center/commitment-automation/software-vs-insurance) — A structural comparison of automation tools versus Archera's insurance-backed approach, with a full feature matrix


# What is Commitment Automation?

What commitment laddering and convertible RI exchange automation are, why an entire vendor category was built around them, and why Archera includes both for free.

Cloud commitments save companies 30–70% on their cloud bills compared to on-demand pricing. They also require making a bet on the future: that you'll be running the same services, at roughly the same scale, for the next 1–3 years.

Most organizations can't make that prediction with confidence. Infrastructure changes with business needs. Teams migrate services. Instance families get replaced by newer ones. Companies get acquired or divest divisions.

Two techniques — commitment laddering and convertible RI exchange — were developed specifically to reduce this exposure. A category of commercial tools was built around automating them. Archera includes both as free platform capabilities.

***

## Commitment Laddering

### The problem

When you buy a 1-year Reserved Instance today, 100% of your commitment risk concentrates at a single renewal date 12 months from now. If your infrastructure has changed by then, you face a choice: renew at terms that no longer fit your workload, or exit the commitment and lose unused savings.

Worse, many organizations don't buy commitments incrementally — they do a periodic "sweep" and commit a large portion of their infrastructure all at once. This creates a cliff: a moment in the future when a large block of commitments expires simultaneously and every prediction you made 12 months ago gets stress-tested at once.

### What laddering does

Commitment laddering distributes purchases across time so that commitment expirations are staggered rather than clustered. Instead of buying 100 EC2 RIs with a 1-year term in January, you might purchase 25 per quarter — so expirations fall in January, April, July, and October of the following year.

This accomplishes several things:

* **Continuous renewal opportunities**: At any given time, a fraction of your commitment portfolio is expiring soon, giving you regular windows to adjust coverage up or down
* **Reduced concentration risk**: No single renewal event can expose you to large unexpected costs
* **Compounding flexibility**: Short-term adjustments compound over time into a portfolio that more accurately reflects your actual infrastructure

Automated laddering tools monitor your commitment portfolio continuously and make incremental purchases on a configurable cadence — daily, weekly, or monthly — maintaining a staggered expiration profile without manual oversight.

***

## Convertible RI Exchange Automation

### The problem

AWS Convertible Reserved Instances offer a specific benefit: they can be exchanged for different instance types, sizes, operating systems, or tenancy configurations before they expire. This is designed to protect buyers against instance family obsolescence — if you committed to an older-generation instance and your workload migrated to a newer one, you can exchange rather than absorb a loss.

The catch is that executing exchanges manually is operationally intensive. You need to monitor which Convertible RIs are currently applied versus idle, track which running instances have no coverage, and identify exchange opportunities that would improve coverage without reducing discount rates. At any meaningful scale, this is a continuous background task.

### What exchange automation does

Convertible RI exchange automation continuously reconciles your running instance portfolio against your held Convertible RI inventory. When your workload shifts — a service migrates from `m5` to `m6i` instances, a team adopts a different operating system, or EC2 fleet composition changes after an autoscaling event — the tool proactively exchanges held RIs to match the new configuration.

This keeps your discount coverage aligned with your actual usage without requiring manual exchange workflows or periodic audits.

***

## Why a Vendor Category Was Built Around These

Commitment laddering and convertible exchange automation are powerful but operationally complex. Both require:

* Continuous ingestion of usage data from cloud billing APIs
* A commitment inventory model that tracks every held RI, its term, expiration, and current utilization
* Logic to identify and execute optimal purchase or exchange actions
* Guardrails to avoid over-committing or triggering adverse exchange terms

Building and maintaining this infrastructure is non-trivial. Several commercial tools were built specifically to provide this capability as a managed service:

{% hint style="info" %}
**Tools in this category include**: ProsperOps (Adaptive Laddering™, Convertible RI Exchange), Spot Eco by NetApp (Layering, Seeding), nOps (Continuous Rebalancing), Harness Cloud Cost Management (Commitment Orchestrator), and Zesty (Dynamic Commitments), among others.

Most charge a share of the savings they generate on your behalf.
{% endhint %}

These tools do real work. Automated laddering and exchange can meaningfully reduce commitment risk compared to manual, periodic purchasing. For organizations that had no commitment management tooling at all, they represent a genuine improvement.

***

## What Archera Includes — At No Additional Charge

Archera's platform includes commitment laddering automation and convertible RI exchange as built-in capabilities. You can configure automation policies that run on weekly, monthly, or quarterly cadences, set savings thresholds that must be met before new commitments are purchased, and review every recommendation before it executes or allow fully autonomous operation.

{% hint style="success" %}
**Archera does not charge a percentage of savings for commitment laddering or exchange automation.** These are included in the platform because Archera's business model is different: Archera earns revenue through a variable risk-based fee on Guaranteed Commitments, not by taking a cut of the savings you achieve.
{% endhint %}

This fee model distinction matters more than it might initially appear. Tools that charge a percentage of savings have an incentive to maximize the commitments you hold — more commitments means more savings to share. Archera's incentive is for your commitments to be well-utilized, because Archera underwrites the downside risk.

***

## The Ceiling of Software-Only Approaches

Commitment laddering and convertible exchange automation reduce commitment risk. They do not eliminate it.

Software can make better decisions about when to purchase commitments and what configuration to target. It cannot guarantee that those commitments will be utilized. If your business changes unexpectedly — a major customer churns, a product line is discontinued, an acquisition changes your cloud footprint — software that optimized your commitment portfolio last month is not on the hook for what happens this month.

This is the structural ceiling of automation-only approaches: they improve the probability of good outcomes, but the financial risk stays with you.

Archera's insurance offering addresses this directly. See [Software-Only vs. Insurance-Backed Commitment Management](/help-center/commitment-automation/software-vs-insurance) for a full comparison.


# Software-Only vs. Insurance-Backed Commitment Management

A structural comparison of software-only commitment automation tools and Archera's insurance-backed approach — what each can and cannot do, and why the distinction matters.

Commitment automation tools — ProsperOps, Spot Eco, nOps, Harness CCM, Zesty, Apptio — all solve a real problem. They reduce the manual overhead of commitment management and can improve coverage and utilization compared to doing nothing. The question isn't whether they work. It's what they can and cannot guarantee.

This page compares the software-only approach to Archera's insurance-backed model across the dimensions that matter most for a commitment management decision.

***

## Feature Comparison

<table><thead><tr><th width="220">Capability</th><th width="110" align="center">Software-Only Tools</th><th width="110" align="center">Archera</th></tr></thead><tbody><tr><td><strong>Commitment laddering automation</strong></td><td align="center">✓ (paid)</td><td align="center">✓ Free</td></tr><tr><td><strong>Convertible RI exchange automation</strong></td><td align="center">✓ (paid)</td><td align="center">✓ Free</td></tr><tr><td><strong>Minimum commitment term</strong></td><td align="center">1 year (native)</td><td align="center">30 days</td></tr><tr><td><strong>Insurance against underutilization</strong></td><td align="center">✗</td><td align="center">✓</td></tr><tr><td><strong>Financial guarantee on commitments</strong></td><td align="center">✗</td><td align="center">✓</td></tr><tr><td><strong>AWS coverage</strong></td><td align="center">✓</td><td align="center">✓</td></tr><tr><td><strong>Azure coverage</strong></td><td align="center">Varies by vendor</td><td align="center">✓</td></tr><tr><td><strong>GCP coverage</strong></td><td align="center">Varies by vendor</td><td align="center">✓</td></tr><tr><td><strong>Pricing model</strong></td><td align="center">Fixed % of savings</td><td align="center">Variable risk-based fee</td></tr><tr><td><strong>Who holds commitment risk</strong></td><td align="center">You</td><td align="center">Archera</td></tr></tbody></table>

{% hint style="info" %}
**Software-only tools** in this comparison include: ProsperOps, Spot Eco by NetApp, nOps, Harness Cloud Cost Management, Zesty, and Apptio Cloudability. Individual capabilities vary by vendor — this table reflects the category as a whole.
{% endhint %}

***

## The Structural Limit of Software-Only

Commitment automation tools are, at their core, better decision-making engines. They analyze your usage history, identify commitment opportunities, purchase commitments at the right time and in the right configuration, and continuously rebalance your portfolio.

What they do not do is change the underlying nature of a cloud commitment. When your tool purchases a 1-year Reserved Instance on your behalf, that commitment still runs for 12 months. If your usage drops — because a customer churns, a workload is deprecated, a team migrates to a new service — you're still paying for unused capacity. The software made a good decision given the information available at the time. The financial exposure is still yours.

{% hint style="warning" %}
**The fundamental limit**: Software can improve the probability that your commitments are well-utilized. It cannot transfer the financial risk when they aren't. That distinction only matters when something unexpected happens — which is exactly when it matters most.
{% endhint %}

Consider a concrete example:

> Your commitment automation tool analyzes your EC2 fleet and recommends purchasing $80,000/month in Savings Plans. The recommendation is sound — your usage has been stable for 8 months. You approve it. Three months later, your largest customer churns and you spin down the associated EC2 fleet. Your on-demand EC2 spend drops 35%. Your Savings Plan commitment does not.

In this scenario, your software tool performed correctly. It had no way to predict the customer churn. You now hold a commitment that's partially unused for the remaining 9 months of its term, and no software feature changes that.

***

## What Insurance Adds

Archera's Guaranteed Commitments (GRIs and GSPs) work differently because Archera is not only a software platform — it's an underwriter.

When you hold a Guaranteed Commitment through Archera, Archera insures the underutilization risk. If your usage drops below what your commitment anticipated, Archera covers the shortfall. The commitment risk has been transferred from your balance sheet to Archera's.

{% hint style="success" %}
**Insurance enables shorter terms**: Because Archera underwrites the downside, it can offer commitment terms as short as 30 days — compared to the 1-year minimum on all native cloud commitment products. Shorter terms mean less exposure per commitment, and more frequent opportunities to right-size your coverage.
{% endhint %}

This is not a software feature. No amount of algorithmic sophistication in a commitment automation tool can replicate this, because optimizing decisions and underwriting outcomes are fundamentally different activities. One requires good software. The other requires taking on financial risk.

***

## The Fee Model Inversion

How a vendor charges you reveals what they're optimizing for.

Software-only tools charge a percentage of the savings they generate. This model has a structural tension: the vendor's revenue is maximized when you hold more commitments, because more commitments produce more savings to share. The tool's incentive is to push commitment coverage higher. In normal conditions, that's fine — higher coverage is generally good. In edge cases — when your workload is volatile, when a change is imminent, when you're near the right coverage level and incremental savings are marginal — the incentive can misalign.

Archera charges a risk-based fee on Guaranteed Commitments — a variable fee calculated based on the term length and the commitment amount. It's the cost of transferring risk, not a share of savings. Archera's revenue depends on the pool of insured commitments being well-underwritten across customers, not on any individual customer maximizing their commitment footprint.

<table><thead><tr><th width="200">Model</th><th>What the vendor earns more of when you...</th><th>Incentive alignment</th></tr></thead><tbody><tr><td><strong>Fixed % of savings</strong></td><td>Hold more commitments, achieve higher coverage</td><td>Aligned on growth; may misalign when commitments should shrink</td></tr><tr><td><strong>Variable risk-based fee</strong></td><td>Hold well-utilized, insured commitments</td><td>Aligned with your utilization; both parties benefit from right-sizing</td></tr></tbody></table>

***

## Why Automation Is Free in Archera

Commitment laddering and convertible exchange automation are not Archera's product. They're infrastructure that makes the insurance product work well.

Archera doesn't charge a savings percentage for automated purchases because the business model doesn't depend on maximizing your commitment coverage. Archera charges a risk-based fee for underwriting risk. The automation is what ensures your commitments are purchased intelligently — that benefits both you and Archera's underwriting book.

This is why Archera can credibly offer both capabilities at no additional charge while simultaneously providing insurance coverage that software tools cannot match. They're complementary, not competing, features.

***

## When Software-Only Is Sufficient

Software-only commitment tools can be the right choice in specific circumstances:

<details>

<summary>You have very stable, predictable workloads</summary>

If your infrastructure has been essentially unchanged for 2+ years and your business gives you high confidence that won't change, the underutilization risk that insurance covers may be low enough that it doesn't justify the premium. In this scenario, an automation tool's laddering and exchange capabilities may deliver the majority of available value.

</details>

<details>

<summary>You're already on 3-year commitments with maximum upfront payment</summary>

If you're already at the maximum native discount tier (3-year, all upfront), you've already made a maximal commitment bet. Adding automation tooling on top may incrementally improve utilization, but the risk posture is already locked in.

</details>

<details>

<summary>You have very small commitment spend</summary>

Below a certain commitment volume, the absolute value of underutilization insurance may not exceed the premium cost. The crossover point varies by workload volatility and premium rates.

</details>

{% hint style="info" %}
For most organizations — particularly those with dynamic infrastructure, multi-cloud environments, or workloads that change with business conditions — the combination of automation and insurance provides meaningfully more value than automation alone.
{% endhint %}

***

## Summary

Software-only commitment tools address a real problem and represent a genuine improvement over unmanaged commitment purchases. The techniques they automate — laddering, convertible exchange, continuous rebalancing — are valuable.

The gap is that they remain software: they help you make better decisions, but the financial consequences of unexpected outcomes stay with you. Archera includes the same automation capabilities, includes them at no additional charge, and adds underwriting against the outcomes that software cannot control.

The result is a commitment strategy that is better optimized *and* insured — which is, by definition, more than any software-only approach can offer.

{% hint style="success" %}
**Ready to see what Guaranteed Commitments look like for your environment?** [Sign up for Archera](https://app.archera.ai/signup) and connect your cloud account — the platform will generate a commitment plan with projected savings and insurance terms within minutes.
{% endhint %}


# Billing

Understand how Archera billing works, how customers pay, and how cloud discounts are attributed across your organization.

## Articles in This Section

* [Billing and GRIs (Guaranteed Reserved Instances)](/help-center/billing/billing-and-gris)
* [How Customers Pay Archera and the Role of GRI Premiums](/help-center/billing/how-customers-pay)
* [AWS Billing - How Archera is Billed Through AWS](/help-center/billing/aws-billing)
* [Azure Billing - How Archera is Billed Through Azure](/help-center/billing/azure-billing)
* [How Do I Apply AWS Credits to My Account?](/help-center/billing/aws-credits)
* [How Does Commitment Discount Attribution Work in Archera?](/help-center/billing/discount-attribution)


# Billing and Guaranteed Commitments

## Understanding Cloud Billing with Archera

Cloud billing refers to how customers are charged for using cloud services — whether directly through a cloud provider like AWS, Azure, GCP or via Archera. Archera helps manage and optimize cloud costs across these providers.

## Archera's Monthly Premium Billing Model

Archera follows a straightforward Monthly Premium-Based Billing Model designed to be transparent and predictable.

### How Our Billing Model Works

**30-Day Consumption Period**

Archera assesses your usage over a configurable 30-day term length. This includes all the services and consumption tracked during that period.

**Invoicing the Following Month**

Once the 30-day period concludes, Archera calculates the charges and issues an invoice in the following month. For example:

* Your November usage will be assessed from November 1st to November 30th
* The invoice for these November charges will be generated and sent in December

### Why This Model?

This approach allows Archera to provide accurate billing based on actual consumption, ensuring you only pay for what you use within the defined period.

### Key Benefits

* **Transparency:** Charges are based on real consumption data
* **Flexibility:** The 30-day term length ensures alignment with standard accounting practices
* **Simplicity:** Predictable billing cycles make it easy to track and reconcile invoices

## Archera's Pricing Structure

Archera's pricing depends on your chosen cloud provider and how services are consumed. Whether you're using AWS, Azure, or another provider, the billing integrates seamlessly with your cloud infrastructure.

## Related Resources

* [How Customers Pay Archera and the Role of GRI Premiums](/help-center/billing/how-customers-pay)
* [AWS Billing - How Archera is Billed Through AWS](/help-center/billing/aws-billing)
* [Azure Billing - How Archera is Billed Through Azure](/help-center/billing/azure-billing)
* [What are Guaranteed Commitments premiums and term lengths?](/help-center/guaranteed-commitments/premiums-and-terms)


# How Customers Pay Archera

## 1. Customer Payment to Archera

Customers pay Archera through:

**Monthly Premium Billing Model:** A fixed cost for accessing Archera's platform, which includes tools for cloud cost optimization, usage insights, and reporting.

**Usage-Based Fees:** Depending on the specific cloud services being monitored and optimized, customers may also pay based on their usage volume (e.g., number of cloud resources tracked or optimized).

These fees are outlined in Archera's pricing plans and can vary depending on the level of service, the features enabled, and the scale of the customer's cloud environment.

## 2. Understanding GRIs (Guaranteed Reserved Instances)

GRIs are a key component of Archera's cloud cost management offering, designed to address the long-term cloud commitments that many customers have made (e.g., Reserved Instances or Savings Plans with cloud providers like AWS and Azure).

These cloud commitments often come with a long-term contract, where customers are locked into paying for a certain amount of resources regardless of whether they use them.

### How GRIs Function

**GRI as a Risk-Based Fee:** Think of a GRI as a risk-based fee. When a customer has cloud commitments they no longer need, Archera helps offload those commitments by taking on the associated risks. In return, Archera charges a risk-based fee to assume the responsibility for those unused commitments.

**Offloading Commitments:** Archera acts as a third party that helps businesses reduce or eliminate financial loss from cloud commitments that are no longer in use. This enables businesses to avoid paying for resources they're not using, and Archera manages the resale or reallocation of those commitments.

## 3. Savings with GRIs and Premiums

The savings shown on the Archera platform reflect the **net savings after GRI premiums are applied**. This means that the savings customers see are already factoring in the cost of the premium that Archera charges for assuming the risk of unused cloud commitments.

**Longer Commitment Terms = Greater Savings:** The longer the term of the commitment the customer is offloading, the greater the savings passed on to the customer.

## 4. Why Archera Charges GRI Premiums

GRI premiums are essential for managing the risk associated with offloading unused cloud commitments.

**Risk Assumption:** When Archera buys back unused cloud commitments or reallocates them, we're taking on the financial risk that those resources cannot be fully utilized. The GRI premium is essentially insurance for Archera in that case.

**Saving the Customer Money:** The GRI premiums allow Archera to provide flexible solutions for customers, helping them get out of long-term, underutilized cloud commitments without taking a significant financial hit.

## Summary

|                         |                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| **What Customers Pay**  | Monthly Premium Billing Model + usage-based fees                                          |
| **GRI Premiums**        | Risk-based fees where Archera assumes risk of unused cloud commitments                    |
| **Savings Calculation** | Net savings after GRI premiums — what you see in Archera already accounts for the premium |
| **Longer Commitments**  | Greater savings, as longer terms are more financially predictable                         |

## Related Resources

* [Billing and GRIs](/help-center/billing/billing-and-gris)
* [AWS Billing - How Archera is Billed Through AWS](/help-center/billing/aws-billing)
* [Azure Billing - How Archera is Billed Through Azure](/help-center/billing/azure-billing)
* [What are Guaranteed Commitments premiums and term lengths?](/help-center/guaranteed-commitments/premiums-and-terms)


# AWS Billing

## Archera's Monthly Premium Billing Model with AWS

Archera uses a Monthly Premium-Based Billing Model that aligns with your actual usage and ensures accurate and transparent invoicing.

**30-Day Consumption Period:** Archera evaluates your usage over a 30-day period to provide a precise breakdown of costs and savings opportunities.

**Invoicing:** At the end of the 30-day period, Archera issues an invoice in the following month based on your usage. For example:

* November's usage is assessed from November 1st to November 30th
* The corresponding invoice is generated and sent in December

## AWS Billing Structure

AWS operates on a **Pay-as-You-Go model**, billing you for the resources you consume:

* Compute, storage, network, and other services
* Billed either by the hour or minute, depending on the service
* Detailed Cost and Usage Reports are provided by AWS, outlining consumption and charges

## How Archera Works with AWS Billing

**Cost Insights:** Archera integrates seamlessly with AWS's billing system to pull detailed usage and cost data, giving you actionable insights into spending trends.

**Cost Optimization:** Archera analyzes your AWS usage patterns and offers recommendations for right-sizing instances, reallocating resources, and eliminating unused assets.

**Cost Alerts:** Archera allows you to set up alerts for budget thresholds, helping you manage and control AWS expenses effectively.

## How Archera is Billed Through AWS

### Direct Billing

You can opt to receive a bill directly from Archera based on the Monthly Premium Billing Model. To enable this, add a payment method (such as a credit card) directly through Archera's website in your Organization's Dashboard.

### Billing Integration via AWS Marketplace

If you purchase Archera through the AWS Marketplace:

* Your Archera fees will appear as a line item on your AWS invoice
* AWS collects the charges and remits them to Archera
* This streamlines the billing process

### Example

If you sign up for Archera through the AWS Marketplace:

* November usage for Archera is included as a line item on your December AWS bill
* AWS handles the collection
* Archera receives the payment seamlessly

## Related Resources

* [Billing and GRIs](/help-center/billing/billing-and-gris)
* [Azure Billing - How Archera is Billed Through Azure](/help-center/billing/azure-billing)
* [What are my Guaranteed Commitment billing options if I'm still on AWS Credits?](/help-center/guaranteed-commitments/billing-options-aws-credits)


# Azure Billing

## Archera's Monthly Premium Billing Model with Azure

Archera operates on a Monthly Premium-Based Billing Model that ensures accuracy and transparency in invoicing.

**30-Day Consumption Period:** Archera monitors your usage over a 30-day period to calculate costs and identify savings opportunities.

**Invoicing:** At the end of each 30-day period, Archera issues an invoice in the following month based on your usage. For example:

* Usage from November 1st to November 30th will be invoiced in December

## Azure Billing Structure

Azure uses a **Pay-as-You-Go model**, charging for the resources consumed based on actual usage:

* Compute, storage, and network services
* Azure provides detailed Cost Management and Billing Reports to help you track and understand your expenses

## How Archera Works with Azure Billing

**Cost Insights:** Archera integrates with Azure's billing data, providing comprehensive insights into your consumption and cost patterns.

**Cost Optimization:** Archera analyzes your Azure usage and offers actionable recommendations, such as rightsizing VMs, optimizing reserved instance usage, and identifying idle resources.

**Cost Alerts:** Archera enables you to set custom cost thresholds to ensure your Azure spending stays within budget.

## How Archera is Billed via Microsoft Azure Marketplace

### Direct Billing

You can choose to receive a bill directly from Archera based on the Monthly Premium Billing Model. To set this up, add a payment method (like a credit card) through Archera's website in your Organization's Dashboard.

### Billing Integration via Microsoft Azure Marketplace

If you purchase Archera through the Azure Marketplace:

* Your Archera charges will appear as a line item on your Azure bill
* Azure will collect these charges as part of your overall Azure invoice
* Azure remits them to Archera, making it convenient to manage costs

### Example

If you subscribe to Archera through the Azure Marketplace:

* Your November usage will appear as a specific line item on your December Azure bill
* Azure handles the collection process

## Related Resources

* [Billing and GRIs](/help-center/billing/billing-and-gris)
* [AWS Billing - How Archera is Billed Through AWS](/help-center/billing/aws-billing)
* [Azure Onboarding - Features](/help-center/azure-onboarding/technical-onboarding/features)


# How Do I Apply AWS Credits?

If you received AWS credits from Archera, another partner, or an AWS team member, you can apply them to your bill through the AWS console.

## Steps

1. Log in to your AWS account
2. Navigate to the Credits tab of the AWS Billing page: <https://console.aws.amazon.com/billing/home#/credits>
3. Enter your one-time-use credit code

To learn more about AWS credits, visit the [official AWS Credits page](https://aws.amazon.com/awscredits/).

## Related Resources

* [What are my Guaranteed Commitment billing options if I'm still on AWS Credits?](/help-center/guaranteed-commitments/billing-options-aws-credits)
* [AWS Billing - How Archera is Billed Through AWS](/help-center/billing/aws-billing)


# How Does Discount Attribution Work?

Discount attribution plays out in various scenarios.

## Multi-Account Setup

The first scenario occurs in a multi-account setup. During a purchase plan, Archera allows you to choose whether to acquire commitments in the master payer account or distribute them across the individual covered accounts. Opt for the option that aligns best with your specific use case.

## Individual Savings Vehicle Attribution

The second scenario involves attributing individual savings vehicles to specific pieces of infrastructure. In this case, Archera can utilize the existing attribution from AWS, Azure, or GCP — or we can customize the attribution to fit your needs.

This is particularly useful when you want to apply specific savings vehicles to particular infrastructure components. For example, you might want to apply a Compute Savings Plan to all Windows-based infrastructure and utilize Guaranteed Commitments for the Linux portion.

Feel free to reach out to us to explore the possibilities of custom attribution at <support@archera.ai>.

## Related Resources

* [How does Archera Attribute Commitment Costs & Savings?](/help-center/user-guide/commitment-attribution)
* [Billing and GRIs](/help-center/billing/billing-and-gris)
* [Why is my dashboard a day or two behind?](/help-center/user-guide/dashboard-day-behind)


# Invoices

## Guaranteed Commitment Billing Process — How It Works

***

## The Billing Lifecycle at a Glance

| Step                                       | What Happens                                                                           | When                                  |
| ------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------- |
| **1. Active Guaranteed Commitments (GCs)** | Customer has purchased GCs that are live in their account                              | Ongoing (e.g., all of January)        |
| **2. Cloud bill finalizes**                | AWS / Azure / GCP closes the billing period and finalizes utilization data for each GC | By the **4th** of the following month |
| **3. Archera invoices**                    | Archera calculates premiums based on actual utilization and publishes the invoice      | **4th** of the following month        |
| **4. Payment collected**                   | Archera charges the customer's payment method (marketplace or credit card)             | \~**6th** of the following month      |

***

## Step-by-Step Breakdown

{% stepper %}
{% step %}

### Customer Has Active GCs

The customer has previously purchased one or more Guaranteed Commitments through Archera. These commitments are live in the customer's cloud account and running throughout the billing period (e.g., January).
{% endstep %}

{% step %}

### Cloud Provider Finalizes the Bill

Once the month ends, the underlying cloud provider (AWS, Azure, or GCP) finalizes the customer's bill. This includes the utilization data for every GC the customer held during that period.

This finalization always completes by the **4th of the following month** (e.g., January data is final by February 4th).
{% endstep %}

{% step %}

### Archera Calculates Premiums & Generates the Invoice

Archera evaluates each GRI individually:

* **GC saved the customer money →** A premium is charged for that GC.
* **GC did not save money →** No premium is charged. Zero.

The invoice is published to the customer's dashboard at [app.archera.ai/invoice](https://app.archera.ai/invoice) on the day after the cloud bill finalizes (the 5th).
{% endstep %}

{% step %}

### Payment Is Collected

Archera charges the customer's payment method on approximately the **6th** of the month. Payment is typically collected via one of two methods:

* **Cloud Marketplace** (AWS / Azure / GCP Marketplace) — the most common method. Note: because the charge is processed in February, marketplace customers will see their January GC premiums appear on their **February** cloud bill. The premiums will show up on the following month’s bill.
* **Credit Card** — charged directly.

**Heads-up for customer conversations:** If a customer is confused about premium timing, help them understand the one-month offset. January premiums show up on the February cloud bill because that's when the marketplace charge is processed — not because the billing is delayed.
{% endstep %}
{% endstepper %}

***

## Rebate GCs — Going Beyond Zero-Risk

For customers on **Rebate GCs**, Archera doesn't just waive premiums on underperforming commitments — it actively pays the customer back.

### How Rebates Work

When a Rebate GC does **not** save money in a given month, Archera credits the customer for their wasted usage. This rebate appears on the same monthly invoice alongside any premiums.

### Where the Rebate Goes

Credits are deposited into the customer's balance in the [Payment Planner](https://app.archera.ai/payment-planner) — a Venmo-like wallet within the Archera platform.

From there, the customer has two options:

1. **Apply credits to GC premiums** — This is the default. The credit automatically reduces what the customer owes on this invoice and future invoices.
2. **Cash out to a bank account** — The customer can request a payout to any bank account of their choice.

***

## Quick-Reference: Customer-Facing FAQ

<details>

<summary>"When will I see my invoice?"</summary>

By the 5th of each month, covering the prior month's GC usage.

</details>

<details>

<summary>"Why does my marketplace bill show GRI charges a month late?"</summary>

Because premiums for a given month are processed the following month (e.g., January premiums are charged in February and appear on your February cloud bill).

</details>

<details>

<summary>"What if my GC doesn't save me anything?"</summary>

You won't be charged a premium for that GC. If you have Rebate GCs, you'll actually receive a credit for the wasted spend.

</details>

<details>

<summary>"How do I use my rebate credits?"</summary>

They're automatically applied to your next invoice by default. You can also request a bank payout through the Payment Planner.

</details>

*Need help walking a customer through their invoice or rebate balance? Reach out in #sales-support on Slack.*


# Signing In to Archera

The ways you and your team can sign in to Archera, plus how to reset a password and verify your email.

Archera offers several ways to sign in, all of which lead to the same platform. You can sign in at [app.archera.ai/login](https://app.archera.ai/login).

## Sign-In Options

### Email and password

Enter your email address and password on the [login page](https://app.archera.ai/login). Repeated failed attempts temporarily lock the account as a security measure.

{% hint style="info" %}
If your organization requires Single Sign-On, password login is turned off and you will be prompted to sign in with SSO instead. See [Single Sign-On (SSO)](/help-center/sign-in-and-security/single-sign-on-sso).
{% endhint %}

### Social sign-in

Sign in with one click using an existing account from:

* **Google**
* **Microsoft**
* **GitHub**
* **Slack**

These options appear on both the login and sign-up pages.

### Single Sign-On (SSO)

If your organization has configured enterprise SSO, click **Single Sign-On** and enter your work email. You will be routed to your company's identity provider to authenticate. New users from a configured email domain are automatically added to the organization.

Administrators can set this up on the [SSO settings page](https://app.archera.ai/settings?tab=sso) — see [Single Sign-On (SSO)](/help-center/sign-in-and-security/single-sign-on-sso).

## Creating an Account

New to Archera? See [How to Sign Up with Archera](https://docs.archera.ai/help-center/archera-getting-started/how-to-sign-up-with-archera) to create an account, or accept an invitation from a colleague. Existing teams can add members from the [invite users guide](https://docs.archera.ai/help-center/user-guide/invite-users).

## Resetting Your Password

1. On the [login page](https://app.archera.ai/login), click **Forgot Password?**
2. Enter your email address. If an account exists, a reset email is sent.
3. Open the link in the email and set a new password.

Already signed in? You can change your password from your account settings.

## Verifying Your Email

Some accounts are asked to confirm their email address by entering a **6-digit code** sent by email. This is a one-time check after signing in, not a step you repeat at every login.

## Multi-Factor Authentication (MFA)

Multi-factor authentication is supported through your identity provider. Enforce MFA in your own IdP and connect it to Archera using [enterprise SSO](/help-center/sign-in-and-security/single-sign-on-sso) — your provider's MFA and security policies then apply whenever your team signs in to Archera.

## Related Resources

* [Single Sign-On (SSO)](/help-center/sign-in-and-security/single-sign-on-sso)
* [Configure SSO for Azure AD](/help-center/sign-in-and-security/how-do-i-configure-sso-for-azure-ad)
* [How Long Is My Data Retained?](/help-center/sign-in-and-security/data-retention)

Still having trouble signing in? Reach out to <support@archera.ai>.


# Single Sign-On (SSO)

How an organization administrator sets up enterprise Single Sign-On (SSO) for Archera, and how to require SSO for all users.

Archera supports enterprise Single Sign-On so your team can sign in with your existing identity provider. SSO is powered by [WorkOS](https://workos.com/docs/sso) and supports both SAML and OIDC connections with all major providers, including Okta, Microsoft Entra ID (Azure AD), Google Workspace, and OneLogin.

{% hint style="info" %}
Setting up SSO requires the **Organization → write** permission. Most organization administrators have this. If the SSO controls are greyed out, ask an administrator to make the change.
{% endhint %}

## Set Up an SSO Connection

{% stepper %}
{% step %}

#### Open SSO settings

Go to [Settings → SSO](https://app.archera.ai/settings?tab=sso) in Archera.
{% endstep %}

{% step %}

#### Add a configuration

In the **SSO Configurations** section, click **Add SSO Configuration**.
{% endstep %}

{% step %}

#### Enter connection details

* **Connection name** (optional) — a label to help you identify this connection later.
* **Domains** (required) — the email domain(s) whose users should sign in through SSO. Separate multiple domains with commas. Your organization's domain is pre-filled. Any user with a matching email domain will be routed to SSO when they sign in.
  {% endstep %}

{% step %}

#### Finish setup in the WorkOS portal

When you submit, Archera creates the connection and opens the **WorkOS admin portal** in a new tab. Follow the instructions there to connect your identity provider — choose SAML or OIDC, exchange metadata or certificates, and map user attributes.
{% endstep %}
{% endstepper %}

The connection is active once it is enabled, its domain matches the user's email, and setup is complete in the WorkOS portal. There is no separate activation or in-app test step.

{% hint style="info" %}
For step-by-step setup with a specific provider, see [Configure SSO for Azure AD](/help-center/sign-in-and-security/how-do-i-configure-sso-for-azure-ad). Instructions for Okta, Google Workspace, and other providers are shown inside the WorkOS admin portal during setup.
{% endhint %}

## Manage a Connection

Each connection in the **SSO Configurations** list has an options menu:

* **Manage** — reopens the WorkOS admin portal to change provider settings.
* **Enable / Disable** — turn the connection on or off. Disabled connections are marked accordingly.
* **Delete** — remove the connection (this also removes it in WorkOS).

{% hint style="warning" %}
Domains cannot be edited in Archera after a connection is created — the in-app menu only offers Manage, Enable/Disable, and Delete. To change domains or provider details, use **Manage** to edit in the WorkOS portal, or delete the connection and create a new one.
{% endhint %}

## Require SSO for All Users (SSO Only)

At the top of the SSO tab, **SSO General Settings** includes an **SSO Only** toggle: *"Require all users to authenticate via SSO."* Turning it on disables email/password login and forces users to sign in through SSO.

{% hint style="warning" %}
Enable **SSO Only** only after you have confirmed SSO works for your team. Note that SSO Only applies to users whose account belongs to a single organization; a user who is a member of more than one organization is not forced through SSO by this setting.
{% endhint %}

## Related Resources

* [Signing In to Archera](/help-center/sign-in-and-security/signing-in-to-archera)
* [Configure SSO for Azure AD](/help-center/sign-in-and-security/how-do-i-configure-sso-for-azure-ad)
* [Settings & Integrations - Section Overview](/help-center/user-guide/settings-integrations)

Questions or issues during setup? Reach out to <support@archera.ai>.




---

[Next Page](/llms-full.txt/1)