### 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**

---

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

#### Example Response

```json
{
  "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**

---

```plaintext
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

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