# Invoices (Beta)

Invoice history endpoints

## List invoices

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

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

## Get invoice by year and month

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

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

## Get invoice line items

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

```json
{"openapi":"3.0.2","info":{"title":"Archera.ai Beta API","version":"v1.0.0"},"tags":[{"name":"Invoices (Beta)","description":"Invoice history endpoints"}],"paths":{"/beta/v1/org/{org_id}/invoices/{year}/{month}/line-items":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLineItem"}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}},"tags":["Invoices (Beta)"],"summary":"Get invoice line items","description":"Returns all line items for the specified invoice, showing per-commitment charges, savings, premiums, and rebates."}}},"components":{"schemas":{"InvoiceLineItem":{"type":"object","properties":{"id":{"type":"string","description":"Line item identifier"},"commitment_id":{"type":"string","description":"Associated commitment identifier"},"commitment":{"description":"Full commitment details (identity, dates, guarantee info, region/instance info, contract term). Metrics (utilization/financials) aren't included here — this invoice line item has its own financials.","allOf":[{"$ref":"#/components/schemas/Commitment"}]},"utilization":{"type":"number","description":"Average utilization for this commitment during the invoice period (0-1)"},"contract_term":{"description":"Contract term of the commitment as it applied during this invoice's billing month — reflects the guarantee lock-in in effect at bill time. Prefer this over `commitment.contract_term`, which reflects the commitment's current term and may have shifted since (e.g. lock-in rolled over, guarantee changed).","type":"string","enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null],"nullable":true},"commitment_financials_invoice_month":{"description":"Actual dollars billed for this line item over the invoice's calendar month. commitment_cost.breakdown.archera_premium is this line item's list-price premium — invoice-wide discount/credits don't attribute per-commitment, so there's no line-item charged value. For the real charged premium on the bill and the full waterfall (list_price, discount, credits), see the parent section's or invoice's `premium_billing`.","allOf":[{"$ref":"#/components/schemas/CommitmentFinancials"}]}},"additionalProperties":false},"Commitment":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique commitment identifier"},"provider_reservation_id":{"type":"string","description":"Cloud provider's ID for this commitment (e.g. AWS reservation ID)"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp","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},"ApiErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"detail":{"nullable":true},"code":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"timestamp":{"type":"string"},"type":{"type":"string"}},"required":["message","timestamp","type"]},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"status":{"type":"string","description":"Error name"},"message":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Errors","additionalProperties":{}}},"additionalProperties":false}},"responses":{"DEFAULT_ERROR":{"description":"Default error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```


---

# 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/invoices-beta.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.