# 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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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":"Commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"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":"Commitment coverage of this service's reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"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","kubernetes","unknown"]},"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":"Commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"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":"Commitment coverage of this service's reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan."},"projected_coverage":{"type":"number","description":"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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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},"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","kubernetes","unknown"]},"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},"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","kubernetes","unknown"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"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","kubernetes","unknown"]},"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},"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","kubernetes","unknown"]},"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},"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","kubernetes","unknown"]},"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},"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":"Mean projected coverage across resources in this group (0-1) — the fraction of each resource's usage THIS plan would cover, averaged. Post-plan / projected: distinct from `resource.coverage` (the trailing-30-day actual 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","kubernetes","unknown"]},"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":"Fraction of this resource's usage THIS plan would cover (0-1). Post-plan / projected — distinct from `resource.coverage`, which is the trailing-30-day actual coverage from existing commitments (the BEFORE picture). For the rolled-up mean across a group, 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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"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_active_commitments":{"type":"integer","description":"Total number of active commitments"},"total_guaranteed_commitments":{"type":"integer","description":"Number of Archera Guaranteed Commitments"},"total_native_commitments":{"type":"integer","description":"Number of native cloud commitments (not guaranteed)"},"average_utilization":{"type":"number","description":"Cost-weighted average utilization across active commitments (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 all active commitments. 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 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","kubernetes","unknown"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"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"}}},"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}}}}
```

## 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","kubernetes","unknown"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"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","kubernetes","unknown"]},"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},"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","kubernetes","unknown"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"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","kubernetes","unknown"]},"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},"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","kubernetes","unknown"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"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","kubernetes","unknown"]},"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},"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 commitment coverage ratio (0-1)","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":"Commitment coverage ratio 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":"Mean commitment coverage across the effective date range (0-1). Share of reservable spend covered by commitments.","nullable":true},"daily":{"type":"array","description":"Per-day data points for trend analysis.","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":"Commitment coverage ratio for this day (0-1)"}},"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 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"}}},"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 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 on-demand (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"}]},"spot_cost":{"type":"number","description":"Cost from spot instances."}},"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 all pricing types (ondemand_cost + commitment_cost.total + spot_cost). 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 on-demand (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"}]},"spot_cost":{"type":"number","description":"Cost from spot instances."}},"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 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"}}},"additionalProperties":false},"PricingTypeBreakdown":{"type":"object","properties":{"ondemand_cost":{"type":"number","description":"Cost from on-demand (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"}]},"spot_cost":{"type":"number","description":"Cost from spot instances."}},"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 all pricing types (ondemand_cost + commitment_cost.total + spot_cost). 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 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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"display_name":{"type":"string","description":"Human-readable commitment name"},"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 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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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 fraction of this resource's usage covered by ALL existing commitments (0-1). Actuals — the BEFORE picture relative to any candidate plan. When this row is nested inside a commitment plan's covered-resources response, this is distinct from the response's per-match `projected_coverage` (the AFTER picture for that specific 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 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","kubernetes","unknown"]},"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 fraction of this resource's usage covered by ALL existing commitments (0-1). Actuals — the BEFORE picture relative to any candidate plan. When this row is nested inside a commitment plan's covered-resources response, this is distinct from the response's per-match `projected_coverage` (the AFTER picture for that specific 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"}}},"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","kubernetes","unknown"]},"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","kubernetes","unknown"]},"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 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":"Monthly on-demand cost (730-hour rate) for the requested quantity. Equals `ondemand_usage_price * quantity * 730`."},"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","kubernetes","unknown"]},"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},"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 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 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","kubernetes","unknown"]},"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},"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 CatalogSKUOfferComparisonResponse object

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"components":{"schemas":{"CatalogSKUOfferComparisonResponse":{"type":"object","properties":{"sku_id":{"type":"string","format":"uuid","description":"The CatalogSKU id compared."},"quantity":{"type":"integer","description":"Quantity hypothetically committed."},"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, collapsed to single-row since catalog comparison is single-SKU. The headline 'should I do this' answer per target is `delta_vs_ondemand.monthly_net_savings`.","items":{"$ref":"#/components/schemas/CatalogSKUTarget"}}},"required":["candidates","ondemand_baseline","quantity","sku_id","targets"],"additionalProperties":false},"CatalogSKUOndemandBaseline":{"type":"object","properties":{"monthly_cost":{"type":"number","description":"Monthly on-demand cost (730-hour rate) for the requested quantity. Equals `ondemand_usage_price * quantity * 730`."},"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","kubernetes","unknown"]},"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},"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 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}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.archera.ai/api-reference/beta-api/models.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.