Exchanges (Beta)

Agent-friendly commitment exchange endpoints

Get Azure exchange recommendations

get

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 (a twin of the Recommended plan without savings plans, which cannot be exchanged), 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_idstring · uuidRequired

Query parameters

providerstring · enumRequired

Cloud provider (aws, azure, gcp)

Example: awsPossible values:

plan_idstring · uuid · 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/beta/v1/org/{org_id}/exchanges/recommendations

HTTPcURLJavaScriptPython

GET /beta/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": "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-16T13:59:49.693Z",
            "end_date": "2026-07-16T13:59:49.693Z",
            "duration_seconds": 1,
            "guarantee_start": "2026-07-16T13:59:49.693Z",
            "guarantee_lockin_date": "2026-07-16T13:59:49.693Z",
            "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-16",
          "utilization": 1
        }
      ],
      "reason": "text",
      "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. 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_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/beta/v1/org/{org_id}/exchanges/recommendations/apply

HTTPcURLJavaScriptPython

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

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