Exchanges

API for commitment exchange recommendations

Get Azure exchange recommendations

get

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_idstring · uuidRequired

Query parameters

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:

plan_idstring · nullableOptional

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_idsstring · uuid[] · nullableOptional

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

application/json

current_utilization_lookback_daysintegerRequired

Number of trailing days of DailyUtilization used for returned-commitment utilization and financials.

204

No Content

400

Bad Request

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

405

Method not allowed

application/json

409

Conflict

application/json

422

Unprocessable Content

application/json

500

Internal server error

application/json

default

Default error response

application/json

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

HTTPcURLJavaScriptPython

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

{
  "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-16",
          "utilization": 1
        }
      ],
      "reason": null,
      "delta_vs_returned": {
        "monthly_net_savings": 1,
        "monthly_commitment_cost": 1,
        "purchase_upfront_cost": 1
      }
    }
  ]
}

Apply Azure exchange recommendations

post

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_idstring · uuidRequired

Body

application/json

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:

Responses

200

OK

application/json

statusstringRequired

Application status for the exchange recommendations.

recommendation_countintegerRequired

Number of exchange recommendations applied.

400

Bad Request

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

405

Method not allowed

application/json

409

Conflict

application/json

422

Unprocessable Content

application/json

500

Internal server error

application/json

default

Default error response

application/json

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

HTTPcURLJavaScriptPython

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
    }
  ]
}

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