Exchanges (Beta) | API & MCP Reference | Archera

Agent-friendly commitment exchange endpoints

Get Azure exchange recommendations

Endpoint

get/beta/v1/org/{org_id}/exchanges/recommendations

Returns Azure reservation exchange recommendations from two sources: plan-derived exchanges that use a commitment plan as the purchase side, and non-plan-derived exchanges that replace eligible 1-year native reservations with same-SKU 1-year GRI purchases backed by 3-year offers. Plan-derived recommendations use either explicit commitments or detected underutilized commitments as the return side. Currently only provider=azure is supported. When plan_id is omitted, the endpoint prefers the latest calculated 'Recommended RIs Only' default plan for the provider-resources segment, falling back to the same Recommended default plan as GET /commitment-plans/recommended when that plan does not exist yet. Returned-commitment utilization and financials use a fixed 3-day lookback. Explicit commitments without DailyUtilization rows in that lookback are excluded.

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 · uuid · 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.
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.

Responses

200 OK:
- 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
default:
- application/json

Example Request

GET /beta/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": "text",
        "contract_term": "one_year_gris",
        "lease_menu_item_id": "123e4567-e89b-12d3-a456-426614174000",
        "quantity": 1,
        "offer": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "provider": "aws",
          "type": "text",
          "region": "text",
          "duration_seconds": 1,
          "instance_type": "text",
          "instance_family": "text",
          "offering_class": "standard",
          "payment_option": "no_upfront",
          "plan_type": "text",
          "product_description": "text",
          "display_name": "text",
          "guaranteed_display_name": "text",
          "is_flexible": true
        },
        "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": "text",
            "billing_account_id": "text",
            "start_date": "2026-07-27T19:35:50.513Z",
            "end_date": "2026-07-27T19:35:50.513Z",
            "duration_seconds": 1,
            "guarantee_start": "2026-07-27T19:35:50.513Z",
            "guarantee_lockin_date": "2026-07-27T19:35:50.513Z",
            "guarantee_method": null,
            "region": "text",
            "instance_type": "text",
            "instance_family": "text",
            "plan_type": "text",
            "payment_option": "no_upfront",
            "offering_class": "standard",
            "is_flexible": true,
            "instance_count": 1,
            "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": "text",
      "delta_vs_returned": {
        "monthly_net_savings": 1,
        "monthly_commitment_cost": 1,
        "purchase_upfront_cost": 1
      }
    }
  ]
}

Apply Azure exchange recommendations

Endpoint

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

Requests application of one Azure reservation exchange recommendation. The request body must contain the exact purchase-side offers and return-side commitments from the recommendation the user approved. 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:
- 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
default:
- application/json

Example Request

POST /beta/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
}