0
# Benefits and Recommendations
1

2
Analyze and optimize Azure Reserved Instances, Savings Plans, and other cost-saving benefits. Get intelligent recommendations for optimal purchasing decisions, track utilization patterns, and maximize return on investment for Azure cost optimization benefits.
3

4
## Capabilities
5

6
### Benefit Recommendations
7

8
Get intelligent recommendations for Azure Reserved Instances, Savings Plans, and other cost optimization benefits based on usage patterns and cost analysis.
9

10
```python { .api }
11
def list(
12
    scope: str,
13
    filter: str = None,
14
    orderby: str = None,
15
    expand: str = None
16
) -> BenefitRecommendationsListResult:
17
    """
18
    List benefit recommendations for the specified scope.
19
    
20
    Args:
21
        scope (str): The scope to get recommendations for
22
        filter (str): OData filter expression for filtering results
23
        orderby (str): OData orderby expression for sorting results
24
        expand (str): Expand options for additional properties
25
    
26
    Returns:
27
        BenefitRecommendationsListResult: Collection of benefit recommendations
28
    """
29
```
30

31
### Benefit Utilization Summaries
32

33
Analyze utilization of existing benefits including Reserved Instances and Savings Plans to optimize usage and identify underutilized resources.
34

35
```python { .api }
36
def list_by_billing_account_id(
37
    billing_account_id: str,
38
    filter: str = None,
39
    grain_parameter: str = None
40
) -> BenefitUtilizationSummariesListResult:
41
    """
42
    List benefit utilization summaries by billing account.
43
    
44
    Args:
45
        billing_account_id (str): The billing account ID
46
        filter (str): OData filter expression
47
        grain_parameter (str): Grain of the summary (Daily, Monthly)
48
    
49
    Returns:
50
        BenefitUtilizationSummariesListResult: Utilization summaries for billing account
51
    """
52

53
def list_by_billing_profile_id(
54
    billing_account_id: str,
55
    billing_profile_id: str,
56
    filter: str = None,
57
    grain_parameter: str = None
58
) -> BenefitUtilizationSummariesListResult:
59
    """
60
    List benefit utilization summaries by billing profile.
61
    
62
    Args:
63
        billing_account_id (str): The billing account ID
64
        billing_profile_id (str): The billing profile ID
65
        filter (str): OData filter expression
66
        grain_parameter (str): Grain of the summary
67
    
68
    Returns:
69
        BenefitUtilizationSummariesListResult: Utilization summaries for billing profile
70
    """
71

72
def list_by_savings_plan_order(
73
    savings_plan_order_id: str,
74
    filter: str = None,
75
    grain_parameter: str = None
76
) -> BenefitUtilizationSummariesListResult:
77
    """
78
    List benefit utilization summaries by savings plan order.
79
    
80
    Args:
81
        savings_plan_order_id (str): The savings plan order ID
82
        filter (str): OData filter expression
83
        grain_parameter (str): Grain of the summary
84
    
85
    Returns:
86
        BenefitUtilizationSummariesListResult: Utilization summaries for savings plan order
87
    """
88

89
def list_by_savings_plan_id(
90
    savings_plan_order_id: str,
91
    savings_plan_id: str,
92
    filter: str = None,
93
    grain_parameter: str = None
94
) -> BenefitUtilizationSummariesListResult:
95
    """
96
    List benefit utilization summaries by specific savings plan.
97
    
98
    Args:
99
        savings_plan_order_id (str): The savings plan order ID
100
        savings_plan_id (str): The specific savings plan ID
101
        filter (str): OData filter expression
102
        grain_parameter (str): Grain of the summary
103
    
104
    Returns:
105
        BenefitUtilizationSummariesListResult: Utilization summaries for specific savings plan
106
    """
107
```
108

109
## Usage Examples
110

111
### Get Reserved Instance Recommendations
112

113
```python
114
# Get RI recommendations for subscription
115
scope = "/subscriptions/{subscription-id}"
116
ri_recommendations = client.benefit_recommendations.list(
117
    scope=scope,
118
    filter="properties/recommendationDetails/recommendedQuantity gt 0",
119
    orderby="properties/recommendationDetails/estimatedSavings desc"
120
)
121

122
print(f"Found {len(ri_recommendations.value)} RI recommendations:")
123
for recommendation in ri_recommendations.value:
124
    props = recommendation.properties
125
    details = props.recommendation_details
126
    
127
    print(f"  Resource Type: {props.resource_type}")
128
    print(f"  Location: {props.location}")
129
    print(f"  Recommended Quantity: {details.recommended_quantity}")
130
    print(f"  Estimated Savings: ${details.estimated_savings:.2f}")
131
    print(f"  Term: {details.term}")
132
    print(f"  Scope: {details.scope}")
133
    print(f"  Look Back Period: {props.look_back_period}")
134
    print("  ---")
135
```
136

137
### Analyze Savings Plan Recommendations
138

139
```python
140
# Get Savings Plan recommendations with expanded details
141
savings_recommendations = client.benefit_recommendations.list(
142
    scope=scope,
143
    filter="kind eq 'SavingsPlan'",
144
    expand="properties/allRecommendationDetails"
145
)
146

147
print("Savings Plan Recommendations:")
148
for recommendation in savings_recommendations.value:
149
    if recommendation.kind == "SavingsPlan":
150
        props = recommendation.properties
151
        
152
        print(f"  Commitment Amount: ${props.commitment_amount}")
153
        print(f"  Annual Savings: ${props.annual_savings_amount:.2f}")
154
        print(f"  Total Cost: ${props.total_cost:.2f}")
155
        print(f"  Coverage Percentage: {props.coverage_percentage:.1f}%")
156
        
157
        # Check all savings details if expanded
158
        if hasattr(props, 'all_recommendation_details'):
159
            for detail in props.all_recommendation_details:
160
                print(f"    Scope: {detail.scope}")
161
                print(f"    Savings: ${detail.estimated_savings:.2f}")
162
```
163

164
### Monitor Reserved Instance Utilization
165

166
```python
167
# Get RI utilization for billing account
168
billing_account_id = "12345678"
169
ri_utilization = client.benefit_utilization_summaries.list_by_billing_account_id(
170
    billing_account_id=billing_account_id,
171
    filter="properties/kind eq 'Reservation'",
172
    grain_parameter="Monthly"
173
)
174

175
print("Reserved Instance Utilization Summary:")
176
for summary in ri_utilization.value:
177
    if summary.kind == "Reservation":
178
        props = summary.properties
179
        
180
        print(f"  Reservation ID: {props.arm_sku_name}")
181
        print(f"  Usage Date: {props.usage_date}")
182
        print(f"  Utilized Percentage: {props.utilized_percentage:.1f}%")
183
        print(f"  Purchased Quantity: {props.purchased_quantity}")
184
        print(f"  Remaining Quantity: {props.remaining_quantity}")
185
        print(f"  Total Reserved Hours: {props.total_reserved_hours}")
186
        print(f"  Used Hours: {props.used_hours}")
187
        print("  ---")
188
```
189

190
### Track Savings Plan Performance
191

192
```python
193
# Get Savings Plan utilization
194
savings_plan_order_id = "sp-order-123"
195
sp_utilization = client.benefit_utilization_summaries.list_by_savings_plan_order(
196
    savings_plan_order_id=savings_plan_order_id,
197
    grain_parameter="Daily"
198
)
199

200
print("Savings Plan Utilization:")
201
total_benefit = 0
202
total_commitment = 0
203

204
for summary in sp_utilization.value:
205
    props = summary.properties
206
    
207
    print(f"  Date: {props.usage_date}")
208
    print(f"  Benefit Amount: ${props.benefit_amount:.2f}")
209
    print(f"  Commitment Amount: ${props.commitment_amount:.2f}")
210
    print(f"  Utilization Percentage: {props.utilization_percentage:.1f}%")
211
    
212
    total_benefit += props.benefit_amount or 0
213
    total_commitment += props.commitment_amount or 0
214

215
if total_commitment > 0:
216
    overall_utilization = (total_benefit / total_commitment) * 100
217
    print(f"\nOverall Utilization: {overall_utilization:.1f}%")
218
```
219

220
### Compare Benefit Types and Scopes
221

222
```python
223
# Get recommendations for different benefit types
224
all_recommendations = client.benefit_recommendations.list(scope=scope)
225

226
# Group by benefit type
227
reservation_recs = []
228
savings_plan_recs = []
229
included_quantity_recs = []
230

231
for rec in all_recommendations.value:
232
    if rec.kind == "Reservation":
233
        reservation_recs.append(rec)
234
    elif rec.kind == "SavingsPlan":
235
        savings_plan_recs.append(rec)
236
    elif rec.kind == "IncludedQuantity":
237
        included_quantity_recs.append(rec)
238

239
print(f"Recommendation Summary:")
240
print(f"  Reserved Instances: {len(reservation_recs)} recommendations")
241
print(f"  Savings Plans: {len(savings_plan_recs)} recommendations")
242
print(f"  Included Quantities: {len(included_quantity_recs)} recommendations")
243

244
# Compare potential savings
245
ri_savings = sum(r.properties.recommendation_details.estimated_savings 
246
                for r in reservation_recs 
247
                if hasattr(r.properties, 'recommendation_details'))
248

249
sp_savings = sum(r.properties.annual_savings_amount 
250
                for r in savings_plan_recs
251
                if hasattr(r.properties, 'annual_savings_amount'))
252

253
print(f"\nPotential Annual Savings:")
254
print(f"  Reserved Instances: ${ri_savings:.2f}")
255
print(f"  Savings Plans: ${sp_savings:.2f}")
256
print(f"  Total: ${ri_savings + sp_savings:.2f}")
257
```
258

259
### Analyze Underutilized Benefits
260

261
```python
262
# Find underutilized reservations
263
underutilized_filter = "properties/utilizedPercentage lt 80 and properties/kind eq 'Reservation'"
264
underutilized = client.benefit_utilization_summaries.list_by_billing_account_id(
265
    billing_account_id=billing_account_id,
266
    filter=underutilized_filter,
267
    grain_parameter="Monthly"
268
)
269

270
print("Underutilized Reservations (< 80% utilization):")
271
for summary in underutilized.value:
272
    props = summary.properties
273
    
274
    print(f"  Resource: {props.arm_sku_name}")
275
    print(f"  Utilization: {props.utilized_percentage:.1f}%")
276
    print(f"  Unused Hours: {props.total_reserved_hours - props.used_hours}")
277
    print(f"  Potential Waste: ${(props.total_reserved_hours - props.used_hours) * props.cost_per_hour:.2f}")
278
    print("  ---")
279
```
280

281
## Data Models
282

283
### Benefit Recommendation Models
284

285
```python { .api }
286
class BenefitRecommendationModel:
287
    id: str
288
    name: str
289
    type: str
290
    kind: BenefitKind
291
    properties: BenefitRecommendationProperties
292

293
class BenefitRecommendationProperties:
294
    first_consumption_date: str
295
    last_consumption_date: str
296
    look_back_period: LookBackPeriod
297
    total_hours: int
298
    device: str
299
    service: str
300
    resource_type: str
301
    location: str
302
    resource_group: str
303
    subscription_id: str
304
    commitment_amount: float
305
    annual_savings_amount: float
306
    total_cost: float
307
    coverage_percentage: float
308
    all_recommendation_details: List[AllSavingsBenefitDetails]
309
    recommendation_details: RecommendationUsageDetails
310

311
class RecommendationUsageDetails:
312
    usage_details: List[dict]
313
    recommended_quantity: float
314
    estimated_savings: float
315
    term: Term
316
    scope: Scope
317

318
class BenefitRecommendationsListResult:
319
    value: List[BenefitRecommendationModel]
320
    next_link: str
321

322
class AllSavingsBenefitDetails:
323
    overshot: float
324
    savings_amount: float
325
    scope: str
326
    estimated_savings: float
327
```
328

329
### Benefit Utilization Models
330

331
```python { .api }
332
class BenefitUtilizationSummary:
333
    id: str
334
    name: str
335
    type: str
336
    kind: BenefitKind
337
    properties: BenefitUtilizationSummaryProperties
338

339
class BenefitUtilizationSummaryProperties:
340
    usage_date: str
341
    arm_sku_name: str
342
    benefit_id: str
343
    benefit_order_id: str
344
    benefit_type: str
345
    utilized_percentage: float
346
    purchased_quantity: float
347
    remaining_quantity: float
348
    total_reserved_hours: float
349
    used_hours: float
350
    unused_hours: float
351
    cost_per_hour: float
352
    commitment_amount: float
353
    benefit_amount: float
354
    utilization_percentage: float
355

356
class SavingsPlanUtilizationSummary:
357
    id: str
358
    name: str
359
    type: str
360
    kind: BenefitKind
361
    properties: SavingsPlanUtilizationSummaryProperties
362

363
class SavingsPlanUtilizationSummaryProperties:
364
    usage_date: str
365
    benefit_id: str
366
    benefit_order_id: str
367
    commitment_amount: float
368
    benefit_amount: float
369
    utilization_percentage: float
370

371
class IncludedQuantityUtilizationSummary:
372
    id: str
373
    name: str
374
    type: str
375
    kind: BenefitKind
376
    properties: IncludedQuantityUtilizationSummaryProperties
377

378
class IncludedQuantityUtilizationSummaryProperties:
379
    usage_date: str
380
    service_name: str
381
    included_quantity: float
382
    utilized_quantity: float
383
    utilization_percentage: float
384

385
class BenefitUtilizationSummariesListResult:
386
    value: List[BenefitUtilizationSummary]
387
    next_link: str
388
```
389

390
## Benefit Enumerations
391

392
```python { .api }
393
class BenefitKind(str, Enum):
394
    INCLUDED_QUANTITY = "IncludedQuantity"
395
    RESERVATION = "Reservation"
396
    SAVINGS_PLAN = "SavingsPlan"
397

398
class LookBackPeriod(str, Enum):
399
    LAST7DAYS = "Last7Days"
400
    LAST30DAYS = "Last30Days"
401
    LAST60DAYS = "Last60Days"
402

403
class Scope(str, Enum):
404
    SINGLE = "Single"
405
    SHARED = "Shared"
406
    MANAGEMENT_GROUP = "ManagementGroup"
407

408
class Term(str, Enum):
409
    P1Y = "P1Y"  # 1 year
410
    P3Y = "P3Y"  # 3 years
411
    P5Y = "P5Y"  # 5 years
412

413
class GrainParameter(str, Enum):
414
    DAILY = "Daily"
415
    MONTHLY = "Monthly"
416
```
417

418
This module provides comprehensive benefit optimization capabilities for maximizing cost savings through intelligent recommendations and detailed utilization tracking of Azure Reserved Instances, Savings Plans, and included quantity benefits.