Exchanges | API & MCP Reference | Archera

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.

Path parameters

org_id string · uuid Required

Query parameters

provider string · enum Required
Cloud provider (aws, azure, gcp)
Example: aws
Possible values: aws azure gcp
plan_id string · nullable Optional
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.

Default: null
commitment_ids string · uuid[] · nullable Optional
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.

Default: null

Responses

200 OK
- Content-Type: application/json
- current_utilization_lookback_days integer Required
  Number of trailing days of DailyUtilization used for returned-commitment utilization and financials.
- data object · ExchangeRecommendation[] Required
  Azure exchange recommendations.
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

GET /v1/org/{org_id}/exchanges/recommendations?provider=aws HTTP/1.1
Accept: */*

Example Response

{
  "current_utilization_lookback_days": 1,
  "data": [
    {
      "purchase_lifetime_commitment": 1,
      "returned_lifetime_commitment": 1,
      "additional_lifetime_commitment": 1,
      "purchase": {
        "account_id": null,
        "contract_term": "one_year_gris",
        "lease_menu_item_id": null,
        "quantity": 1,
        "offer": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "provider": "aws",
          "type": "text",
          "region": null,
          "duration_seconds": 1,
          "instance_type": null,
          "instance_family": null,
          "offering_class": "standard",
          "payment_option": "no_upfront",
          "plan_type": null,
          "product_description": null,
          "display_name": null,
          "guaranteed_display_name": null,
          "is_flexible": null
        },
        "commitment_upfront_cost": 1,
        "commitment_financials_monthly_rate": {
          "commitment_cost": {
            "total": 1,
            "breakdown": {
              "cloud_provider_cost": {
                "total": 1,
                "breakdown": {
                  "recurring": 1,
                  "amortized_upfront": 1
                }
              },
              "archera_premium": 1
            }
          },
          "commitment_savings": {
            "net": 1,
            "gross": 1
          },
          "covered_ondemand_cost": 1
        }
      },
      "returns": [
        {
          "commitment": {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "provider_reservation_id": "text",
            "provider": "aws",
            "display_name": "text",
            "guaranteed_display_name": "text",
            "type": "text",
            "status": "active",
            "is_active": true,
            "is_archera_guaranteed": true,
            "account_id": null,
            "billing_account_id": null,
            "start_date": null,
            "end_date": null,
            "duration_seconds": null,
            "guarantee_start": null,
            "guarantee_lockin_date": null,
            "guarantee_method": null,
            "region": null,
            "instance_type": null,
            "instance_family": null,
            "plan_type": null,
            "payment_option": "no_upfront",
            "offering_class": "standard",
            "is_flexible": null,
            "instance_count": null,
            "contract_term": "one_year_gris"
          },
          "quantity": 1,
          "remaining_lifetime_commitment": 1,
          "utilization": 1,
          "underutilized_commitment_cost": 1,
          "utilization_days": 1,
          "reservation_resource_id": "text",
          "commitment_financials_monthly_rate": {
            "commitment_cost": {
              "total": 1,
              "breakdown": {
                "cloud_provider_cost": {
                  "total": 1,
                  "breakdown": {
                    "recurring": 1,
                    "amortized_upfront": 1
                  }
                },
                "archera_premium": 1
              }
            },
            "commitment_savings": {
              "net": 1,
              "gross": 1
            },
            "covered_ondemand_cost": 1
          }
        }
      ],
      "purchase_commitment_financials_monthly_rate": {
        "commitment_cost": {
          "total": 1,
          "breakdown": {
            "cloud_provider_cost": {
              "total": 1,
              "breakdown": {
                "recurring": 1,
                "amortized_upfront": 1
              }
            },
            "archera_premium": 1
          }
        },
        "commitment_savings": {
          "net": 1,
          "gross": 1
        },
        "covered_ondemand_cost": 1
      },
      "returned_commitment_financials_monthly_rate": {
        "commitment_cost": {
          "total": 1,
          "breakdown": {
            "cloud_provider_cost": {
              "total": 1,
              "breakdown": {
                "recurring": 1,
                "amortized_upfront": 1
              }
            },
            "archera_premium": 1
          }
        },
        "commitment_savings": {
          "net": 1,
          "gross": 1
        },
        "covered_ondemand_cost": 1
      },
      "returned_commitment_daily_utilizations": [
        {
          "date": "2026-07-27",
          "utilization": 1
        }
      ],
      "reason": null,
      "delta_vs_returned": {
        "monthly_net_savings": 1,
        "monthly_commitment_cost": 1,
        "purchase_upfront_cost": 1
      }
    }
  ]
}

Apply Azure exchange recommendations

post/v1/org/{org_id}/exchanges/recommendations/apply

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.

Path parameters

org_id string · uuid Required

Body

provider string · enum Required
Cloud provider (aws, azure, gcp)
Example: aws
Possible values: aws azure gcp
purchases object · ApplyExchangePurchase[] · min: 1 Required
Explicit purchase-side line items for one exchange recommendation.
returns object · ApplyExchangeReturn[] · min: 1 Required
Explicit return-side line items for one exchange recommendation.

Responses

200 OK
- Content-Type: application/json
- status string Required
  Application status for the exchange recommendations.
- recommendation_count integer Required
  Number of exchange recommendations applied.
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not found
405 Method not allowed
409 Conflict
422 Unprocessable Content
500 Internal server error

POST /v1/org/{org_id}/exchanges/recommendations/apply HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 179

{
  "provider": "aws",
  "purchases": [
    {
      "offer_id": "123e4567-e89b-12d3-a456-426614174000",
      "quantity": 1
    }
  ],
  "returns": [
    {
      "commitment_id": "123e4567-e89b-12d3-a456-426614174000",
      "quantity": 1
    }
  ]
}

Example Response

{
  "status": "text",
  "recommendation_count": 1
}