---
title: "Get Azure exchange recommendations"
method: GET
path: "/v1/org/{org_id}/exchanges/recommendations"
tags: ["Exchanges"]
---

# Get Azure exchange recommendations

`GET /v1/org/{org_id}/exchanges/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.

## Query parameters

- `provider` 'aws' | 'azure' | 'gcp', required
- `plan_id` string, uuid, nullable
- `commitment_ids` string[], nullable

## Response `200`

OK

- ExchangeRecommendationsResponse
  - `current_utilization_lookback_days` integer, required — Number of trailing days of DailyUtilization used for returned-commitment utilization and financials.
  - `data` ExchangeRecommendation[], required — Azure exchange recommendations.
    - `purchase_lifetime_commitment` number, required — Lifetime Azure commitment value of the purchase side.
    - `returned_lifetime_commitment` number, required — Lifetime Azure commitment value returned by the exchange.
    - `additional_lifetime_commitment` number, required — Purchase lifetime commitment minus returned lifetime commitment. Azure exchange policy requires this to be non-negative.
    - `purchase` ExchangePurchase, required
      - `account_id` string, nullable — Target cloud account/subscription for the purchase.
      - `contract_term` '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 — User-facing purchase commitment term. For leased/guaranteed purchases this is the lease lock-in term; for native purchases it is the offer duration.
      - `lease_menu_item_id` string, uuid, nullable — Lease menu item attached to the purchase side, or null for native purchases.
      - `quantity` integer, required — Quantity of the Azure reservation to purchase.
      - `offer` CommitmentOffer, required
        - `id` string, uuid — Offer identifier
        - `provider` 'aws' | 'azure' | 'gcp' — Cloud provider (aws, azure, gcp)
        - `type` string — Commitment type (e.g. 'ri', 'savings_plan', 'cud')
        - `region` string, nullable — Cloud region (e.g. 'us-east-1')
        - `duration_seconds` integer — Total commitment duration in seconds
        - `instance_type` string, nullable — Instance type (e.g. 'm5.xlarge'), null for Savings Plans
        - `instance_family` string, nullable — Instance family (e.g. 'm5'), null for some commitment types
        - `offering_class` 'standard' | 'convertible' | 'null', nullable — Offering class (e.g. 'standard', 'convertible')
        - `payment_option` 'no_upfront' | 'partial_upfront' | 'all_upfront' | 'null', nullable — Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')
        - `plan_type` string, nullable — Plan type (e.g. 'Compute', 'EC2Instance')
        - `product_description` string, nullable — Product description (e.g. 'Linux/UNIX')
        - `display_name` string, nullable — Human-readable offer name
        - `guaranteed_display_name` string, nullable — Offer name when purchased as an Archera Guaranteed Commitment
        - `is_flexible` boolean, nullable — Whether the commitment has instance size flexibility
      - `commitment_upfront_cost` number, required — One-time upfront dollars required at signing for the purchase side. NOT a monthly rate.
      - `commitment_financials_monthly_rate` CommitmentFinancialsNoRebate, required
        - `commitment_cost` CommitmentCost
          - `total` number — Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'.
          - `breakdown` CommitmentCostBreakdown
            - `cloud_provider_cost` CloudProviderCost
              - …
            - `archera_premium` number — 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).
        - `commitment_savings` CommitmentSavingsExcludeRebate
          - `net` number — Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'.
          - `gross` number — Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total.
        - `covered_ondemand_cost` number — 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.
    - `returns` ExchangeReturn[], required
      - `commitment` Commitment, required
        - `id` string, uuid, required — Unique commitment identifier
        - `provider_reservation_id` string — Cloud provider's ID for this commitment (e.g. AWS reservation ID)
        - `provider` 'aws' | 'azure' | 'gcp', required — Cloud provider (aws, azure, gcp)
        - `display_name` string — Human-readable commitment name
        - `guaranteed_display_name` string — Commitment name when held as an Archera Guaranteed Commitment
        - `type` string — Commitment type (e.g. 'Compute', 'EC2Instance', 'RDS')
        - `status` 'active' | 'locked' | 'new' | 'reselling' | 'unlocked' | 'unknown' | 'cancelled' | 'expired' | 'recently_expired' | 'resold' | 'removed' — Commitment status (e.g. 'active', 'expired', 'queued')
        - `is_active` boolean — Whether the commitment is currently active
        - `is_archera_guaranteed` boolean — Whether this is an Archera Guaranteed Commitment
        - `account_id` string, nullable — Cloud account ID this commitment is in
        - `billing_account_id` string, nullable — Billing/management account ID
        - `start_date` string, date-time, nullable — When the commitment started
        - `end_date` string, date-time, nullable — When the commitment expires
        - `duration_seconds` integer, nullable — Total commitment duration in seconds
        - `guarantee_start` string, date-time, nullable — When the Archera guarantee period started
        - `guarantee_lockin_date` string, date-time, nullable — When the Archera guarantee lock-in period ends
        - `guarantee_method` unknown
        - `region` string, nullable — Cloud region (e.g. 'us-east-1')
        - `instance_type` string, nullable — Instance type (e.g. 'm5.xlarge')
        - `instance_family` string, nullable — Instance family (e.g. 'm5')
        - `plan_type` string, nullable — Plan type (e.g. 'Compute', 'EC2Instance')
        - `payment_option` 'no_upfront' | 'partial_upfront' | 'all_upfront' | 'null', nullable — Payment option (e.g. 'no_upfront', 'partial_upfront', 'all_upfront')
        - `offering_class` 'standard' | 'convertible' | 'null', nullable — Offering class (e.g. 'standard', 'convertible')
        - `is_flexible` boolean, nullable — Whether the commitment has instance size flexibility
        - `instance_count` integer, nullable — Number of instances covered
        - `contract_term` '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 — Contract term (e.g. 'thirty_day_gris', 'one_year')
      - `quantity` integer, required — Quantity of this commitment proposed for return.
      - `remaining_lifetime_commitment` number, required — Remaining Azure commitment value returned for this commitment quantity. This is lifetime exchange value, not a monthly rate.
      - `utilization` number, required — Whole-commitment utilization of the returned commitment over the DailyUtilization period (0-1).
      - `underutilized_commitment_cost` number, required — Estimated underutilized commitment cost over the DailyUtilization period. This is a period total, not a monthly rate.
      - `utilization_days` integer, required — Number of DailyUtilization days behind the utilization fields.
      - `reservation_resource_id` string, required — Azure reservation resource ID required by Azure exchange APIs.
      - `commitment_financials_monthly_rate` CommitmentFinancialsNoRebate, required
        - `commitment_cost` CommitmentCost
          - `total` number — Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'.
          - `breakdown` CommitmentCostBreakdown
            - `cloud_provider_cost` CloudProviderCost
              - …
            - `archera_premium` number — 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).
        - `commitment_savings` CommitmentSavingsExcludeRebate
          - `net` number — Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'.
          - `gross` number — Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total.
        - `covered_ondemand_cost` number — 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.
    - `purchase_commitment_financials_monthly_rate` CommitmentFinancialsNoRebate, required
      - `commitment_cost` CommitmentCost
        - `total` number — Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'.
        - `breakdown` CommitmentCostBreakdown
          - `cloud_provider_cost` CloudProviderCost
            - `total` number — Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total.
            - `breakdown` CloudProviderCostBreakdown
              - …
          - `archera_premium` number — 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).
      - `commitment_savings` CommitmentSavingsExcludeRebate
        - `net` number — Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'.
        - `gross` number — Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total.
      - `covered_ondemand_cost` number — 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.
    - `returned_commitment_financials_monthly_rate` CommitmentFinancialsNoRebate, required
      - `commitment_cost` CommitmentCost
        - `total` number — Total paid (cloud_provider_cost.total + archera_premium). Headline 'cost'.
        - `breakdown` CommitmentCostBreakdown
          - `cloud_provider_cost` CloudProviderCost
            - `total` number — Amortized cost paid to the cloud provider. Sums with archera_premium to reach cost.total.
            - `breakdown` CloudProviderCostBreakdown
              - …
          - `archera_premium` number — 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).
      - `commitment_savings` CommitmentSavingsExcludeRebate
        - `net` number — Net savings after Archera premium, including any rebate. Actual bill reduction. Headline 'savings'.
        - `gross` number — Savings before Archera premium. Equals covered_ondemand_cost - commitment_cost.breakdown.cloud_provider_cost.total.
      - `covered_ondemand_cost` number — 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.
    - `returned_commitment_daily_utilizations` ExchangeReturnedCommitmentDailyUtilization[], required — Daily whole-commitment utilization for the returned commitments, dollar weighted by each return's commitment cost. Use this for exchange-level utilization charts.
      - `date` string, date, required — DailyUtilization date.
      - `utilization` number, required — Whole-commitment utilization of the returned commitments for this date (0-1), dollar weighted by each return's commitment cost.
    - `reason` string, nullable — Short human-readable reason this exchange was recommended, based on how the exchanger generated it.
    - `delta_vs_returned` ExchangeRecommendationDelta, required
      - `monthly_net_savings` number, required — Purchase monthly net savings minus returned commitments' monthly net savings. Positive means the exchange purchase saves more per 730-hour month.
      - `monthly_commitment_cost` number, required — Purchase monthly commitment cost minus returned commitments' monthly commitment cost. Positive means more monthly commitment spend.
      - `purchase_upfront_cost` number, required — Purchase-side one-time upfront cost only. Not netted against returned commitments because returned financials are monthly-rate utilization actuals and have no upfront component. NOT a rate.

## Other responses

- `204` — No Content
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `405` — Method not allowed
- `409` — Conflict
- `422` — Unprocessable Content
- `500` — Internal server error
- `default` — Default error response

---

[API](https://skmtc.dev/archera/apis/archera-ai-api.md) · [All operations](https://skmtc.dev/archera/apis/archera-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/archera/archera-ai-api/revisions/fefab54846a2/schema)