Exchanges

API for commitment exchange recommendations

Get Azure exchange recommendations

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

{"openapi":"3.1.0","info":{"title":"Archera.ai API","version":"v1.0.0"},"tags":[{"name":"Exchanges","description":"API for commitment exchange recommendations"}],"paths":{"/v1/org/{org_id}/exchanges/recommendations":{"get":{"parameters":[{"in":"query","name":"provider","description":"Cloud provider (aws, azure, gcp)","schema":{"type":"string","enum":["aws","azure","gcp"]},"required":true},{"in":"query","name":"plan_id","description":"Optional commitment plan ID to use for plan-derived exchange purchases. When omitted, the endpoint prefers the latest calculated 'Recommended RIs Only' default plan for the provider-resources segment — a twin of the Recommended plan without savings plans, which cannot be exchanged — falling back to the same Recommended default plan selected by GET /commitment-plans/recommended when that plan does not exist yet. Responses may also include non-plan-derived native-to-GRI exchanges.","schema":{"type":["string","null"],"format":"uuid","default":null},"required":false},{"in":"query","name":"commitment_ids","description":"Optional explicit Azure commitment IDs to consider returning. When omitted, the exchanger detects underutilized exchange candidates from the default 3-day DailyUtilization lookback. Explicit commitments without utilization rows in that lookback are excluded. Mutually exclusive with plan_id.","schema":{"type":"array","null"},"default":null,"items":{"type":"string","format":"uuid"}},"required":false,"explode":true,"style":"form"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeRecommendationsResponse"}}},"204":{"description":"No Content"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"422":{"$ref":"#/components/responses/UNPROCESSABLE_CONTENT"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"default":{"$ref":"#/components/responses/DEFAULT_ERROR"}}],"tags":["Exchanges"],"summary":"Get Azure exchange recommendations","description":"Returns Azure reservation exchange recommendations using the same recommendation logic as the beta exchange endpoint, including plan-derived exchanges and eligible same-SKU 1-year native to 1-year GRI exchanges. When plan_id is omitted, the endpoint prefers the latest calculated 'Recommended RIs Only' default plan for the provider-resources segment (a twin of the Recommended plan without savings plans, which cannot be exchanged), falling back to the Recommended default plan when that plan does not exist yet. Currently only provider=azure is supported."}}},"components":{"schemas":{"ExchangeRecommendationsResponse":{"type":"object","properties":{"current_utilization_lookback_days":{"type":"integer","description":"Number of trailing days of DailyUtilization used for returned-commitment utilization and financials."},"data":{"type":"array","description":"Azure exchange recommendations.","items":{"$ref":"#/components/schemas/ExchangeRecommendation"}}},"required":["current_utilization_lookback_days","data"],"additionalProperties":false},"ExchangeRecommendation":{"type":"object","properties":{"purchase_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value of the purchase side."},"returned_lifetime_commitment":{"type":"number","description":"Lifetime Azure commitment value returned by the exchange."},"additional_lifetime_commitment":{"type":"number","description":"Purchase lifetime commitment minus returned lifetime commitment. Azure exchange policy requires this to be non-negative."},"purchase":{"$ref":"#/components/schemas/ExchangePurchase"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeReturn"}},"purchase_commitment_financials_monthly_rate":{"description":"Purchase-side monthly-rate financials.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"returned_commitment_financials_monthly_rate":{"description":"Returned commitments' rolled-up monthly-rate financials for the selected integer return quantities. Cost comes from DailyUtilization commitment cost, and savings are computed after assigning as much utilization as possible to the quantity that remains committed. Rebate and Archera premium are excluded from exchange recommendations and are not included in net savings.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"},"returned_commitment_daily_utilizations":{"type":"array","description":"Daily whole-commitment utilization for the returned commitments, dollar weighted by each return's commitment cost. Use this for exchange-level utilization charts.","items":{"$ref":"#/components/schemas/ExchangeReturnedCommitmentDailyUtilization"}},"reason":{"type":["string","null"],"description":"Short human-readable reason this exchange was recommended, based on how the exchanger generated it."},"delta_vs_returned":{"description":"Purchase-side economics compared with returned-commitment economics. Monthly fields are purchase-side minus returned-side; purchase_upfront_cost is purchase-side one-time upfront only and is not netted. Purchase financials come from plan-amortized line item financials; returned financials come from DailyUtilization cost and covered usage for the selected integer return quantities, normalized to 730-hour monthly rates.","$ref":"#/components/schemas/ExchangeRecommendationDelta"}},"required":["additional_lifetime_commitment","delta_vs_returned","purchase","purchase_commitment_financials_monthly_rate","purchase_lifetime_commitment","returned_commitment_daily_utilizations","returned_commitment_financials_monthly_rate","returned_lifetime_commitment","returns"],"additionalProperties":false},"ExchangePurchase":{"type":"object","properties":{"account_id":{"type":["string","null"],"description":"Target cloud account/subscription for the purchase."},"contract_term":{"description":"User-facing purchase commitment term. For leased/guaranteed purchases this is the lease lock-in term; for native purchases it is the offer duration.","type":["string","null"],"enum":["one_year_gris","thirty_day_gris","two_month_gris","three_month_gris","four_month_gris","five_month_gris","six_month_gris","seven_month_gris","eight_month_gris","nine_month_gris","ten_month_gris","eleven_month_gris","twelve_month_gris","thirteen_month_gris","fourteen_month_gris","fifteen_month_gris","sixteen_month_gris","seventeen_month_gris","eighteen_month_gris","nineteen_month_gris","twenty_month_gris","twenty_one_month_gris","twenty_two_month_gris","twenty_three_month_gris","twenty_four_month_gris","twenty_five_month_gris","twenty_six_month_gris","twenty_seven_month_gris","twenty_eight_month_gris","twenty_nine_month_gris","thirty_month_gris","thirty_one_month_gris","thirty_two_month_gris","thirty_three_month_gris","thirty_four_month_gris","thirty_five_month_gris","one_year","two_year","three_year","five_year","zero_day","thirty_day","two_month","three_month","four_month","five_month","six_month","seven_month","eight_month","nine_month","ten_month","eleven_month","thirteen_month","fourteen_month","fifteen_month","sixteen_month","seventeen_month","eighteen_month","nineteen_month","twenty_month","twenty_one_month","twenty_two_month","twenty_three_month","twenty_five_month","twenty_six_month","twenty_seven_month","twenty_eight_month","twenty_nine_month","thirty_month","thirty_one_month","thirty_two_month","thirty_three_month","thirty_four_month","thirty_five_month",null]},"lease_menu_item_id":{"type":["string","null"],"format":"uuid","description":"Lease menu item attached to the purchase side, or null for native purchases."},"quantity":{"type":"integer","description":"Quantity of the Azure reservation to purchase."},"offer":{"description":"Azure reservation offer being purchased.","$ref":"#/components/schemas/CommitmentOffer"},"commitment_upfront_cost":{"type":"number","description":"One-time upfront dollars required at signing for the purchase side. NOT a monthly rate."},"commitment_financials_monthly_rate":{"type":"string","description":"Purchase-side plan line item economics as 730-hour monthly rates.","$ref":"#/components/schemas/CommitmentFinancialsNoRebate"}},"required":["commitment_financials_monthly_rate","commitment_upfront_cost","offer","quantity"],"additionalProperties":false},"CommitmentOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Offer identifier"},"provider":{"description":"Cloud provider (aws, azure, gcp)","type":"string","enum":["aws","azure","gcp"]},"type":{"type":"string","description":"Commitment type (e.g. 'ri', 'savings_plan', 'cud')"},"region":{"type":["string","null"],"description":"Cloud region (e.g. 'us-east-1')"},"duration_seconds":{"type":"integer","description":"Total commitment duration in seconds"},"instance_type":{"type":["string","null"],"description":"Instance type (e.g. 'm5.xlarge'), null for Savings Plans"},"instance_family":{"type":["string","null"],"description":"Instance family (e.g. 'm5'), null for some commitment types"},"offering_class":{"description":"Offering class (e.g. 'standard', 'convertible')","type":["string","null"],"enum":["standard","convertible",null]},"payment_option":{"description":"Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')","type":["string","null"],"enum":["no_upfront","partial_upfront","all_upfront",null]},"plan_type":{"type":["string","null"],"description":"Plan type (e.g. 'Compute', 'EC2Instance')"},"product_description":{"type":["string","null"],"description":"Product description (e.g. 'Linux/UNIX')"},"display_name":{"type":["string","null"],"description":"Human-readable offer name"},"guaranteed_display_name":{"type":["string","null"],"description":"Offer name when purchased as an Archera Guaranteed Commitment"},"is_flexible":{"type":["boolean","null"],"description":"Whether the commitment has instance size flexibility"}},"additionalProperties":false},"CommitmentFinancialsNoRebate":{"type":"object","properties":{"commitment_cost":{"$ref":"#/components/schemas/CommitmentCost"},"commitment_savings":{"$ref":"#/components/schemas/CommitmentSavings_Exclude_Rebate"},"covered_ondemand_cost":{"type":"number","description":"On-demand cost of usage covered by commitments — baseline for savings. NOT a cost paid by the user. Equals commitment_cost.breakdown.cloud_provider_cost.total + commitment_savings.gross."}}}}}}

## Apply Azure exchange recommendations

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

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