For the complete documentation index, see [llms.txt](https://docs.archera.ai/llms.txt). This page is also available as [Markdown](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta.md). GitBook AssistantAsk On this page Agent-friendly commitment plan endpoints GitBook Assistant ### List commitment plans[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#get-beta-v1-org-org_id-commitment-plans) get/beta/v1/org/{org\_id}/commitment-plans Returns commitment plans scoped to one segment for the given provider. `segment_id` defaults to the provider-resources segment — same fallback as POST/PUT — so the typical caller sees the plans tied to their default segment without cross-segment duplicates. Further filters (template, status, flags) narrow within that scope. Coverage metrics (current\_coverage / projected\_coverage) are omitted here for speed; fetch the detail endpoint for those. GitBook Assistant Path parameters org\_idstring · uuidRequired Query parameters providerstring · enumRequired Cloud provider (aws, azure, gcp) Example: `aws`Possible values: `aws``azure``gcp` segment\_idstring · uuid · nullableOptional Optional segment ID to scope results. Defaults to the provider resources segment if not specified. Default: `null` template\_idstring · uuid · nullableOptional Filter to plans generated from this template (GET /commitment-plan-templates) Default: `null` statusstring · enum · nullableOptional Filter by plan status (e.g. 'draft', 'in\_progress') Default: `null`Possible values: `new``reviewed``scheduled``completed``draft``needs_review``in_progress``null` is\_recommendedboolean · nullableOptional Filter to the flagged recommended plan Default: `null` is\_system\_generatedboolean · nullableOptional Filter to system-generated (default) plans — the three built-ins (Recommended / Balanced / High Savings) vs. user-created plans. Default: `null` is\_renewalboolean · nullableOptional Switch which flavor the list returns. Omitted (default) and false both return segment-scoped non-renewal plans — backward-compatible with the pre-renewal contract. Set to true to fetch renewal plans (which aren't segment-scoped — `segment_id` is ignored). There's no combined view; renewals and non-renewals are queried separately. Default: `null` Responses 200 OK application/json idstring · uuidRequired Unique plan identifier providerstring · enumRequired Cloud provider (aws, azure, gcp) Possible values: `aws``azure``gcp` namestringRequired Plan name (e.g. 'Recommended', 'Balanced', 'High Savings') descriptionstring · nullableOptional Human-readable summary of the plan is\_renewalbooleanRequired True if this plan was created to renew a set of expiring commitments — `configuration.renewal_commitment_ids` is populated when true. False otherwise (covers both purchase and infrastructure flavors — the distinction is not user-meaningful, both cover uncovered resources with new commitments). statusstring · enumRequired Plan status (e.g. 'draft', 'in\_progress', 'completed') Possible values: `new``reviewed``scheduled``completed``draft``needs_review``in_progress` is\_calculatingbooleanRequired True if the plan is still being computed created\_atstring · date-timeRequired When the plan was generated usage\_start\_datestring · date-time · nullableOptional Start of the usage window the plan was computed from. Null on renewal plans — renewals derive their window from the source commitments' end dates, not from a lookback (see configuration.renewal\_commitment\_ids). usage\_end\_datestring · date-time · nullableOptional End of the usage window the plan was computed from. Null on renewal plans (see usage\_start\_date). max\_termstring · nullableRequired Maximum commitment term (e.g. '30\_DAY', '1\_YEAR', '3\_YEAR') minimum\_commitmentnumberRequired Minimum total spend being committed to breakeven\_daysanyRead-onlyOptional Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand. commitment\_upfront\_costnumberOptional One-time total dollars required at signing if this plan is applied. NOT a rate — do not sum with monthly-rate fields. Typically 0 for the Recommended plan; can be significant for High Savings / All Upfront plans. Always mention explicitly to the user when non-zero. commitment\_financials\_monthly\_rateobject · CommitmentFinancialsNoRebateOptional Show properties configurationobject · CommitmentPlanConfigurationOptional Show properties 400 Bad request application/json 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}/commitment-plans HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` GET /beta/v1/org/{org_id}/commitment-plans?provider=aws HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ``` [\ {\ "id": "123e4567-e89b-12d3-a456-426614174000",\ "provider": "aws",\ "name": "text",\ "description": "text",\ "is_renewal": true,\ "status": "new",\ "is_calculating": true,\ "created_at": "2026-07-27T19:35:56.493Z",\ "usage_start_date": "2026-07-27T19:35:56.493Z",\ "usage_end_date": "2026-07-27T19:35:56.493Z",\ "max_term": "text",\ "minimum_commitment": 1,\ "breakeven_days": 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\ },\ "configuration": {\ "max_upfront_cost": 0,\ "lookback_days": 1,\ "contract_specs": [\ {\ "commitment_type": "text",\ "contract_term": "one_year_gris",\ "payment_option": "no_upfront"\ }\ ],\ "resource_ids": [],\ "renewal_commitment_ids": [\ "123e4567-e89b-12d3-a456-426614174000"\ ]\ }\ }\ ] ``` ### Create a commitment plan[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#post-beta-v1-org-org_id-commitment-plans) post/beta/v1/org/{org\_id}/commitment-plans Creates a new commitment plan for the given segment. The plan is generated asynchronously; the response echoes the initial plan with is\_calculating=true and omits coverage fields (meaningless mid-recalc). Poll GET /commitment-plans/{plan\_id} once is\_calculating=false to get the full detail including coverage and per-service breakdowns. GitBook Assistant Path parameters org\_idstring · uuidRequired Body application/json application/json providerstring · enumRequired Cloud provider (aws, azure, gcp) Example: `aws`Possible values: `aws``azure``gcp` segment\_idstring · uuid · nullableOptional Optional segment ID to scope results. Defaults to the provider resources segment if not specified. Default: `null` namestringRequired Human-readable plan name configurationobject · CommitmentPlanConfigurationRequired Show properties Responses 200 OK application/json idstring · uuidRequired Unique plan identifier providerstring · enumRequired Cloud provider (aws, azure, gcp) Possible values: `aws``azure``gcp` namestringRequired Plan name (e.g. 'Recommended', 'Balanced', 'High Savings') descriptionstring · nullableOptional Human-readable summary of the plan is\_renewalbooleanRequired statusstring · enumRequired Plan status (e.g. 'draft', 'in\_progress', 'completed') Possible values: `new``reviewed``scheduled``completed``draft``needs_review``in_progress` is\_calculatingbooleanRequired True if the plan is still being computed created\_atstring · date-timeRequired When the plan was generated usage\_start\_datestring · date-time · nullableOptional usage\_end\_datestring · date-time · nullableOptional End of the usage window the plan was computed from. Null on renewal plans (see usage\_start\_date). max\_termstring · nullableRequired Maximum commitment term (e.g. '30\_DAY', '1\_YEAR', '3\_YEAR') minimum\_commitmentnumberRequired Minimum total spend being committed to breakeven\_daysanyRead-onlyOptional Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand. commitment\_upfront\_costnumberOptional commitment\_financials\_monthly\_rateobject · CommitmentFinancialsNoRebateOptional Show properties configurationobject · CommitmentPlanConfigurationOptional Show properties 400 Bad request application/json 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}/commitment-plans HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` POST /beta/v1/org/{org_id}/commitment-plans HTTP/1.1 Content-Type: application/json Accept: */* Content-Length: 333 { "provider": "aws", "segment_id": "123e4567-e89b-12d3-a456-426614174000", "name": "text", "configuration": { "max_upfront_cost": 0, "lookback_days": 1, "contract_specs": [\ {\ "commitment_type": "text",\ "contract_term": "one_year_gris",\ "payment_option": "no_upfront"\ }\ ], "resource_ids": [], "renewal_commitment_ids": [\ "123e4567-e89b-12d3-a456-426614174000"\ ] } } ``` 200 OK GitBook AssistantAskCopy ``` { "id": "123e4567-e89b-12d3-a456-426614174000", "provider": "aws", "name": "text", "description": "text", "is_renewal": true, "status": "new", "is_calculating": true, "created_at": "2026-07-27T19:35:56.493Z", "usage_start_date": "2026-07-27T19:35:56.493Z", "usage_end_date": "2026-07-27T19:35:56.493Z", "max_term": "text", "minimum_commitment": 1, "breakeven_days": 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 }, "configuration": { "max_upfront_cost": 0, "lookback_days": 1, "contract_specs": [\ {\ "commitment_type": "text",\ "contract_term": "one_year_gris",\ "payment_option": "no_upfront"\ }\ ], "resource_ids": [], "renewal_commitment_ids": [\ "123e4567-e89b-12d3-a456-426614174000"\ ] } } ``` ### Create a renewal commitment plan[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#post-beta-v1-org-org_id-commitment-plans-renewals) post/beta/v1/org/{org\_id}/commitment-plans/renewals Creates a new commitment plan that renews a set of expiring commitments. The plan covers the same resources the source commitments were covering, with the contract specs supplied in `configuration` driving the renewal recommendation. The plan is generated asynchronously — the response echoes the initial plan with `is_calculating=true`; poll GET /commitment-plans/{plan\_id} until that flips to see the generated line items. GitBook Assistant Renewal plans always sit on the provider-resources segment; `segment_id` is not accepted. The usage window the recommender feeds on is derived automatically from the source commitments' end dates, so `configuration.lookback_days` is omitted (the field is rejected if sent). `configuration.resource_ids` is also rejected — `configuration.renewal_commitment_ids` carries the scope for a renewal plan, parallel to how `configuration.resource_ids` scopes an infrastructure plan on the regular create endpoint. GitBook Assistant Each generated line item carries a `renewal_commitment_id` linking it back to the source commitment it is proposed to replace. Pair with GET /commitment-plans/{plan\_id}/renewal-commitments to see the source commitments side-by-side. GitBook Assistant Path parameters org\_idstring · uuidRequired Body application/json application/json providerstring · enumRequired Cloud provider (aws, azure, gcp) Example: `aws`Possible values: `aws``azure``gcp` namestringRequired Human-readable plan name configurationobject · RenewalCommitmentPlanConfigurationRequired Show properties Responses 200 OK application/json idstring · uuidRequired Unique plan identifier providerstring · enumRequired Cloud provider (aws, azure, gcp) Possible values: `aws``azure``gcp` namestringRequired Plan name (e.g. 'Recommended', 'Balanced', 'High Savings') descriptionstring · nullableOptional Human-readable summary of the plan is\_renewalbooleanRequired statusstring · enumRequired Plan status (e.g. 'draft', 'in\_progress', 'completed') Possible values: `new``reviewed``scheduled``completed``draft``needs_review``in_progress` is\_calculatingbooleanRequired True if the plan is still being computed created\_atstring · date-timeRequired When the plan was generated usage\_start\_datestring · date-time · nullableOptional usage\_end\_datestring · date-time · nullableOptional End of the usage window the plan was computed from. Null on renewal plans (see usage\_start\_date). max\_termstring · nullableRequired Maximum commitment term (e.g. '30\_DAY', '1\_YEAR', '3\_YEAR') minimum\_commitmentnumberRequired Minimum total spend being committed to breakeven\_daysanyRead-onlyOptional Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand. commitment\_upfront\_costnumberOptional commitment\_financials\_monthly\_rateobject · CommitmentFinancialsNoRebateOptional Show properties configurationobject · CommitmentPlanConfigurationOptional Show properties 400 Bad request application/json 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}/commitment-plans/renewals HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` POST /beta/v1/org/{org_id}/commitment-plans/renewals HTTP/1.1 Content-Type: application/json Accept: */* Content-Length: 245 { "provider": "aws", "name": "text", "configuration": { "max_upfront_cost": 0, "contract_specs": [\ {\ "commitment_type": "text",\ "contract_term": "one_year_gris",\ "payment_option": "no_upfront"\ }\ ], "renewal_commitment_ids": [\ "123e4567-e89b-12d3-a456-426614174000"\ ] } } ``` 200 OK GitBook AssistantAskCopy ### Get default commitment plans[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#get-beta-v1-org-org_id-commitment-plans-default) get/beta/v1/org/{org\_id}/commitment-plans/default Returns the three default Archera commitment plans: Recommended (30-day), Balanced (1-year), and High Savings (3-year). GitBook Assistant Path parameters org\_idstring · uuidRequired Query parameters providerstring · enumRequired Cloud provider (aws, azure, gcp) Example: `aws`Possible values: `aws``azure``gcp` segment\_idstring · uuid · nullableOptional Optional segment ID to scope results. Defaults to the provider resources segment if not specified. Default: `null` Responses 200 OK application/json idstring · uuidRequired Unique plan identifier providerstring · enumRequired Cloud provider (aws, azure, gcp) Possible values: `aws``azure``gcp` namestringRequired Plan name (e.g. 'Recommended', 'Balanced', 'High Savings') descriptionstring · nullableOptional Human-readable summary of the plan is\_renewalbooleanRequired statusstring · enumRequired Plan status (e.g. 'draft', 'in\_progress', 'completed') Possible values: `new``reviewed``scheduled``completed``draft``needs_review``in_progress` is\_calculatingbooleanRequired True if the plan is still being computed created\_atstring · date-timeRequired When the plan was generated usage\_start\_datestring · date-time · nullableOptional usage\_end\_datestring · date-time · nullableOptional End of the usage window the plan was computed from. Null on renewal plans (see usage\_start\_date). max\_termstring · nullableRequired Maximum commitment term (e.g. '30\_DAY', '1\_YEAR', '3\_YEAR') minimum\_commitmentnumberRequired Minimum total spend being committed to breakeven\_daysanyRead-onlyOptional Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand. commitment\_upfront\_costnumberOptional commitment\_financials\_monthly\_rateobject · CommitmentFinancialsNoRebateOptional Show properties configurationobject · CommitmentPlanConfigurationOptional Show properties current\_coveragenumberRequired Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan. projected\_coveragenumberRequired Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan. 400 Bad request application/json 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}/commitment-plans/default HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` GET /beta/v1/org/{org_id}/commitment-plans/default?provider=aws HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ### Get recommended commitment plan[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#get-beta-v1-org-org_id-commitment-plans-recommended) get/beta/v1/org/{org\_id}/commitment-plans/recommended Returns the single recommended commitment plan for the organization. This is typically the 30-day Recommended plan. Returns 204 if no plan is available. GitBook Assistant Path parameters org\_idstring · uuidRequired Query parameters providerstring · enumRequired Cloud provider (aws, azure, gcp) Example: `aws`Possible values: `aws``azure``gcp` segment\_idstring · uuid · nullableOptional Optional segment ID to scope results. Defaults to the provider resources segment if not specified. Default: `null` Responses 200 OK application/json idstring · uuidRequired Unique plan identifier providerstring · enumRequired Cloud provider (aws, azure, gcp) Possible values: `aws``azure``gcp` namestringRequired Plan name (e.g. 'Recommended', 'Balanced', 'High Savings') descriptionstring · nullableOptional Human-readable summary of the plan is\_renewalbooleanRequired statusstring · enumRequired Plan status (e.g. 'draft', 'in\_progress', 'completed') Possible values: `new``reviewed``scheduled``completed``draft``needs_review``in_progress` is\_calculatingbooleanRequired True if the plan is still being computed created\_atstring · date-timeRequired When the plan was generated usage\_start\_datestring · date-time · nullableOptional usage\_end\_datestring · date-time · nullableOptional End of the usage window the plan was computed from. Null on renewal plans (see usage\_start\_date). max\_termstring · nullableRequired Maximum commitment term (e.g. '30\_DAY', '1\_YEAR', '3\_YEAR') minimum\_commitmentnumberRequired Minimum total spend being committed to breakeven\_daysanyRead-onlyOptional Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand. commitment\_upfront\_costnumberOptional commitment\_financials\_monthly\_rateobject · CommitmentFinancialsNoRebateOptional Show properties configurationobject · CommitmentPlanConfigurationOptional Show properties current\_coveragenumberRequired Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan. projected\_coveragenumberRequired Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan. 204 No Content 400 Bad request application/json 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}/commitment-plans/recommended HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` GET /beta/v1/org/{org_id}/commitment-plans/recommended?provider=aws HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ### Get commitment plan details[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#get-beta-v1-org-org_id-commitment-plans-plan_id) get/beta/v1/org/{org\_id}/commitment-plans/{plan\_id} Returns details for a specific commitment plan by ID, including per-service breakdowns. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Responses 200 OK application/json idstring · uuidRequired Unique plan identifier providerstring · enumRequired Cloud provider (aws, azure, gcp) Possible values: `aws``azure``gcp` namestringRequired Plan name (e.g. 'Recommended', 'Balanced', 'High Savings') descriptionstring · nullableOptional Human-readable summary of the plan is\_renewalbooleanRequired statusstring · enumRequired Plan status (e.g. 'draft', 'in\_progress', 'completed') Possible values: `new``reviewed``scheduled``completed``draft``needs_review``in_progress` is\_calculatingbooleanRequired True if the plan is still being computed created\_atstring · date-timeRequired When the plan was generated usage\_start\_datestring · date-time · nullableOptional usage\_end\_datestring · date-time · nullableOptional End of the usage window the plan was computed from. Null on renewal plans (see usage\_start\_date). max\_termstring · nullableRequired Maximum commitment term (e.g. '30\_DAY', '1\_YEAR', '3\_YEAR') minimum\_commitmentnumberRequired Minimum total spend being committed to breakeven\_daysanyRead-onlyOptional Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand. commitment\_upfront\_costnumberOptional commitment\_financials\_monthly\_rateobject · CommitmentFinancialsNoRebateOptional Show properties configurationobject · CommitmentPlanConfigurationOptional Show properties current\_coveragenumberRequired Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan. projected\_coveragenumberRequired Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan. covered\_servicesobject · CoveredService\[\]Optional List of cloud services covered by this plan, with per-service savings and commitment breakdowns Show properties 400 Bad request application/json 401 Unauthorized application/json 403 Forbidden application/json 404 Not Found 405 Method not allowed application/json 409 Conflict application/json 500 Internal server error application/json default Default error response application/json get/beta/v1/org/{org\_id}/commitment-plans/{plan\_id} HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` GET /beta/v1/org/{org_id}/commitment-plans/{plan_id} HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ### Update a commitment plan[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#put-beta-v1-org-org_id-commitment-plans-plan_id) put/beta/v1/org/{org\_id}/commitment-plans/{plan\_id} Update the plan's name and/or configuration. Replacing `configuration` triggers a recalculation — the response will have is\_calculating=true and line-item financials are invalid until generation completes. Rejected if the plan is currently calculating, is a system-generated default, or is locked for purchase. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Body application/json application/json namestringOptional New plan name configurationobject · CommitmentPlanConfigurationOptional Show properties Responses 200 OK application/json idstring · uuidRequired Unique plan identifier providerstring · enumRequired Cloud provider (aws, azure, gcp) Possible values: `aws``azure``gcp` namestringRequired Plan name (e.g. 'Recommended', 'Balanced', 'High Savings') descriptionstring · nullableOptional Human-readable summary of the plan is\_renewalbooleanRequired statusstring · enumRequired Plan status (e.g. 'draft', 'in\_progress', 'completed') Possible values: `new``reviewed``scheduled``completed``draft``needs_review``in_progress` is\_calculatingbooleanRequired True if the plan is still being computed created\_atstring · date-timeRequired When the plan was generated usage\_start\_datestring · date-time · nullableOptional usage\_end\_datestring · date-time · nullableOptional End of the usage window the plan was computed from. Null on renewal plans (see usage\_start\_date). max\_termstring · nullableRequired Maximum commitment term (e.g. '30\_DAY', '1\_YEAR', '3\_YEAR') minimum\_commitmentnumberRequired Minimum total spend being committed to breakeven\_daysanyRead-onlyOptional Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand. commitment\_upfront\_costnumberOptional commitment\_financials\_monthly\_rateobject · CommitmentFinancialsNoRebateOptional Show properties configurationobject · CommitmentPlanConfigurationOptional Show properties 400 Bad request application/json 401 Unauthorized application/json 403 Forbidden application/json 404 Not Found 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 put/beta/v1/org/{org\_id}/commitment-plans/{plan\_id} HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` PUT /beta/v1/org/{org_id}/commitment-plans/{plan_id} HTTP/1.1 Content-Type: application/json Accept: */* Content-Length: 264 { "name": "text", "configuration": { "max_upfront_cost": 0, "lookback_days": 1, "contract_specs": [\ {\ "commitment_type": "text",\ "contract_term": "one_year_gris",\ "payment_option": "no_upfront"\ }\ ], "resource_ids": [], "renewal_commitment_ids": [\ "123e4567-e89b-12d3-a456-426614174000"\ ] } } ``` 200 OK GitBook AssistantAskCopy ### Delete a commitment plan[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#delete-beta-v1-org-org_id-commitment-plans-plan_id) delete/beta/v1/org/{org\_id}/commitment-plans/{plan\_id} Delete a commitment plan. Rejected if the plan is currently calculating, is a system-generated default, or is locked for purchase. Irreversible. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Responses 204 No Content ``` No content ``` 400 Bad request application/json 401 Unauthorized application/json 403 Forbidden application/json 404 Not Found 405 Method not allowed application/json 409 Conflict application/json 500 Internal server error application/json default Default error response application/json delete/beta/v1/org/{org\_id}/commitment-plans/{plan\_id} HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` DELETE /beta/v1/org/{org_id}/commitment-plans/{plan_id} HTTP/1.1 Accept: */* ``` 204 No Content ``` No content ``` ### Apply (purchase) a commitment plan[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#post-beta-v1-org-org_id-commitment-plans-plan_id-apply) post/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/apply Executes the plan's selected line items as actual commitment purchases. Marks the plan as edited and records the initiating user. The plan is then processed by the commitment-purchase workflow — inspect the plan status afterwards for progress. Rejected if the plan is currently calculating or already locked. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Responses 200 OK application/json idstring · uuidRequired Unique plan identifier providerstring · enumRequired Cloud provider (aws, azure, gcp) Possible values: `aws``azure``gcp` namestringRequired Plan name (e.g. 'Recommended', 'Balanced', 'High Savings') descriptionstring · nullableOptional Human-readable summary of the plan is\_renewalbooleanRequired statusstring · enumRequired Plan status (e.g. 'draft', 'in\_progress', 'completed') Possible values: `new``reviewed``scheduled``completed``draft``needs_review``in_progress` is\_calculatingbooleanRequired True if the plan is still being computed created\_atstring · date-timeRequired When the plan was generated usage\_start\_datestring · date-time · nullableOptional usage\_end\_datestring · date-time · nullableOptional End of the usage window the plan was computed from. Null on renewal plans (see usage\_start\_date). max\_termstring · nullableRequired Maximum commitment term (e.g. '30\_DAY', '1\_YEAR', '3\_YEAR') minimum\_commitmentnumberRequired Minimum total spend being committed to breakeven\_daysanyRead-onlyOptional Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand. commitment\_upfront\_costnumberOptional commitment\_financials\_monthly\_rateobject · CommitmentFinancialsNoRebateOptional Show properties configurationobject · CommitmentPlanConfigurationOptional Show properties current\_coveragenumberRequired Spend-based commitment coverage of reservable spend today, from existing commitments (0-1) — the BEFORE picture, pre-plan. projected\_coveragenumberRequired Spend-based commitment coverage of reservable spend if this plan is applied (0-1) — the AFTER picture, post-plan. covered\_servicesobject · CoveredService\[\]Optional List of cloud services covered by this plan, with per-service savings and commitment breakdowns Show properties 400 Bad request application/json 401 Unauthorized application/json 403 Forbidden application/json 404 Not Found 405 Method not allowed application/json 409 Conflict application/json 500 Internal server error application/json default Default error response application/json post/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/apply HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` POST /beta/v1/org/{org_id}/commitment-plans/{plan_id}/apply HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ### Copy a commitment plan, optionally applying line-item edits[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#post-beta-v1-org-org_id-commitment-plans-plan_id-copy) post/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/copy Creates a draft copy of an existing commitment plan, including its line items and resource matches. The copy is a regular user-created plan (is\_default=false, is\_recommended=false) and is editable via PUT /commitment-plans/{plan\_id}. Useful for forking a system-generated default plan (Recommended / Balanced / High Savings) so it can be modified — defaults themselves are read-only. The copy inherits the source plan's already-computed line items and financials, so it is ready immediately (is\_calculating=false). GitBook Assistant Optionally apply line-item edits during the copy via two mutually exclusive modes: GitBook Assistant - Explicit: pass `line_item_updates` referencing the SOURCE plan's line\_item\_ids; the server translates them to the copy's new IDs internally and applies them atomically. GitBook Assistant - Resolution: pass `target_contract_term` (\+ optional `target_payment_option` / `target_line_item_ids`) and the server swaps every selected (or scoped) line item on the copy to the closest candidate at or below the target term. Saves the LLM having to enumerate per-line edits when the user wants a uniform shape change on the new plan. GitBook Assistant If any edit fails (unknown source line\_item\_id, invalid offer, integer-coercion error on a unit-basis offer's `selected_amount`, duplicate line\_item\_id within `line_item_updates`), the entire copy + updates rolls back — no orphan copy persists. This is the canonical 'copy to edit' workflow; saves the round trip and ID-translation logic vs a separate copy + update sequence. GitBook Assistant Returns the new plan in CommitmentPlanListSchema shape — id + headline financials + configuration; covered\_services and coverage fields are intentionally omitted because computing them eagerly loads per-service summaries (expensive) and the typical caller just needs the post-edit totals to confirm the copy. Follow up with `commitment_plan_details` on the returned id if you need the full breakdown. In resolution mode the response additionally carries a `resolution` array with one entry per scoped line item (`actual_term` / `actual_payment_option` / `actual_term_reason` of `exact_match`, `fallback_closest_shorter`, or `no_alternative`). Surface no\_alternative outcomes to the user so they understand why coverage may be partial. GitBook Assistant Rejected if the source plan is currently being calculated. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Body application/json application/json target\_contract\_termstring · enum · nullableOptional Server-side resolution mode. Set to a target contract term and the server resolves the per-line-item update set using the same fallback rule the comparison endpoint projects: exact match on (term, payment) where available, else closest shorter term with the same payment option (GRI preferred within tier). Mutually exclusive with explicit per-line-item updates — pass one OR the other, not both. Preferred over enumerating updates manually because the server can't silently omit entries from a list it builds itself. Default: `null`Possible values: `one_year_gris``thirty_day_gris``two_month_gris``three_month_gris``four_month_gris``five_month_gris``six_month_gris``seven_month_gris``eight_month_gris``nine_month_gris``ten_month_gris``eleven_month_gris``twelve_month_gris``thirteen_month_gris``fourteen_month_gris``fifteen_month_gris``sixteen_month_gris``seventeen_month_gris``eighteen_month_gris``nineteen_month_gris``twenty_month_gris``twenty_one_month_gris``twenty_two_month_gris``twenty_three_month_gris``twenty_four_month_gris``twenty_five_month_gris``twenty_six_month_gris``twenty_seven_month_gris``twenty_eight_month_gris``twenty_nine_month_gris``thirty_month_gris``thirty_one_month_gris``thirty_two_month_gris``thirty_three_month_gris``thirty_four_month_gris``thirty_five_month_gris``one_year``two_year``three_year``five_year``zero_day``thirty_day``two_month``three_month``four_month``five_month``six_month``seven_month``eight_month``nine_month``ten_month``eleven_month``thirteen_month``fourteen_month``fifteen_month``sixteen_month``seventeen_month``eighteen_month``nineteen_month``twenty_month``twenty_one_month``twenty_two_month``twenty_three_month``twenty_five_month``twenty_six_month``twenty_seven_month``twenty_eight_month``twenty_nine_month``thirty_month``thirty_one_month``thirty_two_month``thirty_three_month``thirty_four_month``thirty_five_month``null` target\_payment\_optionstring · enumOptional Target payment option for resolution mode. Defaults to no\_upfront — most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Ignored when `target_contract_term` is null. Default: `no_upfront`Possible values: `no_upfront``partial_upfront``all_upfront` target\_line\_item\_idsstring · uuid\[\] · nullableOptional Optional subset of line items to update under resolution mode. If omitted, applies to all selected line items in the plan. Ignored when `target_contract_term` is null. Default: `null` namestring · nullableOptional Name for the copied plan. If omitted, defaults to ' '. Default: `null` line\_item\_updatesobject · LineItemUpdateEntry\[\] · nullableOptional Optional list of line-item edits to apply during the copy. Each entry has the same shape as `update_commitment_plan_line_items`'s `updates` (line\_item\_id + optional is\_selected / account\_id / offer-swap triple). Entries reference the SOURCE plan's line\_item\_ids; the server translates them to the copy's new IDs internally and applies them atomically. If any edit fails, the entire copy + updates rolls back. Use this for the canonical 'copy to edit' workflow — saves the round trip and ID-translation logic that would otherwise live on the client. Mutually exclusive with `target_contract_term` (resolution mode). Default: `null` Show properties Responses 200 OK application/json idstring · uuidRequired Unique plan identifier providerstring · enumRequired Cloud provider (aws, azure, gcp) Possible values: `aws``azure``gcp` namestringRequired Plan name (e.g. 'Recommended', 'Balanced', 'High Savings') descriptionstring · nullableOptional Human-readable summary of the plan is\_renewalbooleanRequired statusstring · enumRequired Plan status (e.g. 'draft', 'in\_progress', 'completed') Possible values: `new``reviewed``scheduled``completed``draft``needs_review``in_progress` is\_calculatingbooleanRequired True if the plan is still being computed created\_atstring · date-timeRequired When the plan was generated usage\_start\_datestring · date-time · nullableOptional usage\_end\_datestring · date-time · nullableOptional End of the usage window the plan was computed from. Null on renewal plans (see usage\_start\_date). max\_termstring · nullableRequired Maximum commitment term (e.g. '30\_DAY', '1\_YEAR', '3\_YEAR') minimum\_commitmentnumberRequired Minimum total spend being committed to breakeven\_daysanyRead-onlyOptional Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand. commitment\_upfront\_costnumberOptional commitment\_financials\_monthly\_rateobject · CommitmentFinancialsNoRebateOptional Show properties configurationobject · CommitmentPlanConfigurationOptional Show properties resolutionobject · HypotheticalLineItem\[\] · nullableOptional Per-line-item resolution outcome when `target_contract_term` was passed. One entry per line item that was IN SCOPE for the request (covers `no_alternative` items too — those are not in the applied updates but are surfaced here so callers can see what the server couldn't satisfy). `actual_term_reason` is one of: `exact_match` (landed at target), `fallback_closest_shorter` (used the longest available term ≤ target with same payment option), `no_alternative` (no candidate satisfied — line item left unchanged). Absent / null on explicit-mode calls. Show properties 400 Bad Request 401 Unauthorized application/json 403 Forbidden application/json 404 Not Found 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}/commitment-plans/{plan\_id}/copy HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` POST /beta/v1/org/{org_id}/commitment-plans/{plan_id}/copy HTTP/1.1 Content-Type: application/json Accept: */* Content-Length: 402 { "target_contract_term": "one_year_gris", "target_payment_option": "no_upfront", "target_line_item_ids": [\ "123e4567-e89b-12d3-a456-426614174000"\ ], "name": "text", "line_item_updates": [\ {\ "line_item_id": "123e4567-e89b-12d3-a456-426614174000",\ "is_selected": true,\ "account_id": "text",\ "offer_id": "123e4567-e89b-12d3-a456-426614174000",\ "lease_menu_item_id": "123e4567-e89b-12d3-a456-426614174000",\ "selected_amount": 1\ }\ ] } ``` 200 OK GitBook AssistantAskCopy ### Get commitment plan line items[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#get-beta-v1-org-org_id-commitment-plans-plan_id-line-items) get/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/line-items Returns individual commitment recommendations within a plan, including offer details, per-line-item savings, and costs. Each line item has an is\_selected field: if false, the line item is excluded from the plan and its costs/savings are NOT included in the plan's top-level metrics. Pass `line_item_ids` to fetch a specific subset (e.g. a single line item). GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Query parameters line\_item\_idsstring · uuid\[\] · nullableOptional Optional list of line-item ids to scope the response to. When omitted, returns every line item in the plan. Default: `null` renewal\_commitment\_idsstring · uuid\[\] · nullableOptional Renewal plans only: scope to line items proposed as the replacement for these specific expiring commitments. Useful for "show me what's being proposed to replace commitment X." Rejected with 400 on non-renewal plans (their line items have no renewal linkage; this guards against stale/wrong plan ids silently returning unrelated rows). Default: `null` order\_bystring · enumOptional Field to order results by Default: `monthly_net_savings`Possible values: `monthly_net_savings``monthly_total_cost``breakeven_days``discount_rate``upfront_cost` descbooleanOptional Sort descending (default true) Default: `true` pageinteger · min: 1OptionalDefault: `1` page\_sizeinteger · min: 1 · max: 10000OptionalDefault: `20` Responses 200 OK application/json Headersobject Show Header Responseobject · CommitmentLineItem\[\] Show properties 400 Bad request application/json 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}/commitment-plans/{plan\_id}/line-items HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ``` [\ {\ "id": "123e4567-e89b-12d3-a456-426614174000",\ "is_selected": true,\ "account_id": "text",\ "contract_term": "one_year_gris",\ "contract_spec": {\ "commitment_type": "text",\ "properties": {\ "ANY_ADDITIONAL_PROPERTY": "anything"\ },\ "term": "one_year_gris",\ "payment_option": "no_upfront"\ },\ "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\ },\ "discount_rate": 1,\ "breakeven_days": null,\ "selected_amount": null,\ "recommended_amount": 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\ },\ "covered_services": [\ "text"\ ],\ "renewal_commitment_id": "123e4567-e89b-12d3-a456-426614174000"\ }\ ] ``` ### Update commitment plan line items[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#post-beta-v1-org-org_id-commitment-plans-plan_id-line-items-update) post/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/line-items/update Atomically apply line-item edits in a single request. Two modes: GitBook Assistant - Explicit: pass `updates`, a list where each entry carries the same fields the singular line-item update would accept (selection, account, offer-swap triple) plus the `line_item_id` selector. GitBook Assistant - Resolution: pass `target_contract_term` (\+ optional `target_payment_option` / `target_line_item_ids`) and the server swaps every selected (or scoped) line item to the closest candidate at or below the target term. Saves the LLM having to enumerate many edits when the user wants a uniform shape change. GitBook Assistant Modes are mutually exclusive. All updates are applied within a single transaction — if any fails (unknown line item, invalid offer, integer-coercion error on a unit-basis offer's `selected_amount`), the whole call is rejected and no changes persist. GitBook Assistant Returns the updated plan in CommitmentPlanListSchema shape — id + headline financials + configuration; covered\_services and coverage fields are intentionally omitted because computing them eagerly loads per-service summaries (expensive) and the typical caller just needs the post-edit totals to confirm the change. Follow up with `commitment_plan_details` on the returned id if you need the full breakdown. In resolution mode the response additionally carries a `resolution` array with one entry per scoped line item: the `actual_term` / `actual_payment_option` applied and an `actual_term_reason` of `exact_match`, `fallback_closest_shorter`, or `no_alternative` (the latter were left untouched). Surface no\_alternative outcomes to the user so they understand why coverage may be partial. GitBook Assistant Rejected if the parent plan is currently calculating, is a system-generated default, or is locked for purchase. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Body application/json application/json target\_contract\_termstring · enum · nullableOptional target\_payment\_optionstring · enumOptional Default: `no_upfront`Possible values: `no_upfront``partial_upfront``all_upfront` target\_line\_item\_idsstring · uuid\[\] · nullableOptional Default: `null` updatesobject · LineItemUpdateEntry\[\] · min: 1 · nullableOptional List of per-line-item updates to apply atomically. Required unless `target_contract_term` is set (resolution mode). Each entry's `line_item_id` must be on the parent plan. Default: `null` Show properties Responses 200 OK application/json idstring · uuidRequired Unique plan identifier providerstring · enumRequired Cloud provider (aws, azure, gcp) Possible values: `aws``azure``gcp` namestringRequired Plan name (e.g. 'Recommended', 'Balanced', 'High Savings') descriptionstring · nullableOptional Human-readable summary of the plan is\_renewalbooleanRequired statusstring · enumRequired Plan status (e.g. 'draft', 'in\_progress', 'completed') Possible values: `new``reviewed``scheduled``completed``draft``needs_review``in_progress` is\_calculatingbooleanRequired True if the plan is still being computed created\_atstring · date-timeRequired When the plan was generated usage\_start\_datestring · date-time · nullableOptional usage\_end\_datestring · date-time · nullableOptional End of the usage window the plan was computed from. Null on renewal plans (see usage\_start\_date). max\_termstring · nullableRequired Maximum commitment term (e.g. '30\_DAY', '1\_YEAR', '3\_YEAR') minimum\_commitmentnumberRequired Minimum total spend being committed to breakeven\_daysanyRead-onlyOptional Days until the plan pays for itself. If commitments are kept for at least this many days, the plan is a more profitable decision than running on-demand. commitment\_upfront\_costnumberOptional commitment\_financials\_monthly\_rateobject · CommitmentFinancialsNoRebateOptional Show properties configurationobject · CommitmentPlanConfigurationOptional Show properties resolutionobject · HypotheticalLineItem\[\] · nullableOptional Show properties 400 Bad Request 401 Unauthorized application/json 403 Forbidden application/json 404 Not Found 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}/commitment-plans/{plan\_id}/line-items/update HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` POST /beta/v1/org/{org_id}/commitment-plans/{plan_id}/line-items/update HTTP/1.1 Content-Type: application/json Accept: */* Content-Length: 378 { "target_contract_term": "one_year_gris", "target_payment_option": "no_upfront", "target_line_item_ids": [\ "123e4567-e89b-12d3-a456-426614174000"\ ], "updates": [\ {\ "line_item_id": "123e4567-e89b-12d3-a456-426614174000",\ "is_selected": true,\ "account_id": "text",\ "offer_id": "123e4567-e89b-12d3-a456-426614174000",\ "lease_menu_item_id": "123e4567-e89b-12d3-a456-426614174000",\ "selected_amount": 1\ }\ ] } ``` 200 OK GitBook AssistantAskCopy ### List the commitments being renewed by a renewal plan[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#get-beta-v1-org-org_id-commitment-plans-plan_id-renewal-commitments) get/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/renewal-commitments Returns the expiring commitments that a renewal plan is proposed to replace — identity, dates, guarantee info, and contract term. Ordered by `end_date` ascending (earliest-expiring first) so the caller surfaces the most-urgent renewals first. GitBook Assistant Rejected with 400 if the plan is not a renewal plan — for non-renewal plans use /line-items or /covered-resources instead. GitBook Assistant To filter to the commitments tied to a subset of line items, pass `line_item_ids`. To go the other direction (line items proposed as replacements for a given source commitment), use the `renewal_commitment_ids` filter on /line-items. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Query parameters line\_item\_idsstring · uuid\[\] · nullableOptional Optional list of line-item ids to scope to. When supplied, returns only the source commitments whose renewing line items are in this set. Default: `null` pageinteger · min: 1OptionalDefault: `1` page\_sizeinteger · min: 1 · max: 200OptionalDefault: `50` Responses 200 OK application/json Headersobject Show Header Responseobject · Commitment\[\] Show properties 400 Bad request application/json 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}/commitment-plans/{plan\_id}/renewal-commitments HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/renewal-commitments HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ``` [\ {\ "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:56.493Z",\ "end_date": "2026-07-27T19:35:56.493Z",\ "duration_seconds": 1,\ "guarantee_start": "2026-07-27T19:35:56.493Z",\ "guarantee_lockin_date": "2026-07-27T19:35:56.493Z",\ "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"\ }\ ] ``` ### Compare commitment offers across a plan's line items[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#get-beta-v1-org-org_id-commitment-plans-plan_id-comparison) get/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/comparison Returns per-line-item offer alternatives plus plan-wide rollups for each (contract\_term, payment\_option) hypothetical. Designed to answer 'what would the plan look like at 3-year' in a single call: hypothetical\_totals carries the rolled-up financials and delta\_vs\_current, with per-line-item resolution exposed for transparency. Each line item lands at the target term when available, else the longest available term <= target with the same payment option (GRI preferred within tier), else its current term. Defaults: line\_item\_ids=all selected, contract\_terms=all distinct in candidates, payment\_options=\[no\_upfront\]. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Query parameters line\_item\_idsstring · uuid\[\] · nullableOptional Optional subset of line items to compare. If omitted, defaults to all selected line items in the plan. Default: `null` contract\_termsstring · enum\[\] · nullableOptional Optional list of target terms to roll up. If omitted, the response includes a hypothetical for every distinct contract\_term that appears in any line item's candidates after the payment-option filter. Default: `null` Show properties payment\_optionsstring · enum\[\]Optional Payment options to include. Defaults to no\_upfront only — most users are uncomfortable with cash at signing, so this matches the default framing for plan comparisons. Pass partial\_upfront / all\_upfront explicitly to surface those. Show properties Responses 200 OK application/json current\_totalsobject · LineItemOfferComparisonTotalsRequired Show properties hypothetical\_totalsobject · HypotheticalTotal\[\]Required One entry per (contract\_term, payment\_option) combination requested (or per distinct term present in candidates if contract\_terms was omitted). Each entry's totals + delta\_vs\_current answer 'what's the plan-wide impact of this term?' in one place — no client-side summing across line items required. Show properties dataobject · LineItemOfferComparisonRow\[\]Required Per-line-item detail. Use when the user wants to drill into 'why does RDS not have a 3-year candidate' or to assemble an update payload. Show properties 400 Bad Request 401 Unauthorized application/json 403 Forbidden application/json 404 Not Found 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}/commitment-plans/{plan\_id}/comparison HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/comparison HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ``` { "current_totals": { "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 }, "commitment_upfront_cost": 1 }, "hypothetical_totals": [\ {\ "contract_term": "one_year_gris",\ "payment_option": "no_upfront",\ "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\ },\ "commitment_upfront_cost": 1,\ "delta_vs_current": {\ "monthly_net_savings": 1,\ "monthly_commitment_cost": 1,\ "upfront_cost": 1\ },\ "line_items": [\ {\ "line_item_id": "123e4567-e89b-12d3-a456-426614174000",\ "actual_term": "one_year_gris",\ "actual_payment_option": "no_upfront",\ "actual_term_reason": "exact_match"\ }\ ]\ }\ ], "data": [\ {\ "line_item_id": "123e4567-e89b-12d3-a456-426614174000",\ "current": {\ "is_current": true,\ "offer_id": "123e4567-e89b-12d3-a456-426614174000",\ "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\ },\ "lease_menu_item_id": "123e4567-e89b-12d3-a456-426614174000",\ "selected_amount": 1,\ "contract_term": "one_year_gris",\ "discount_rate": 1,\ "breakeven_days": 1,\ "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\ },\ "delta_vs_current": {\ "monthly_net_savings": 1,\ "upfront_cost": 1,\ "discount_rate": 1,\ "breakeven_days": 1\ }\ },\ "candidates": [\ {\ "is_current": true,\ "offer_id": "123e4567-e89b-12d3-a456-426614174000",\ "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\ },\ "lease_menu_item_id": "123e4567-e89b-12d3-a456-426614174000",\ "selected_amount": 1,\ "contract_term": "one_year_gris",\ "discount_rate": 1,\ "breakeven_days": 1,\ "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\ },\ "delta_vs_current": {\ "monthly_net_savings": 1,\ "upfront_cost": 1,\ "discount_rate": 1,\ "breakeven_days": 1\ }\ }\ ]\ }\ ] } ``` ### List filterable covered-resource attributes for a plan[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#get-beta-v1-org-org_id-commitment-plans-plan_id-covered-resources-attributes) get/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/covered-resources/attributes Returns the fields that can be used in the `filter` parameter of /commitment-plans//covered-resources, scoped to the resources the plan actually covers. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Responses 200 OK application/json namestringRequired fieldstringRequired typestring · enumRequiredPossible values: `boolean``integer``float``date``datetime``time``currency``percent``string``enum``uuid``tags` 400 Bad request application/json 401 Unauthorized application/json 403 Forbidden application/json 404 Not found application/json 405 Method not allowed application/json 409 Conflict application/json 500 Internal server error application/json default Default error response application/json get/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/covered-resources/attributes HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ``` [\ {\ "name": "text",\ "field": "text",\ "type": "boolean"\ }\ ] ``` ### Get valid values for a filterable covered-resource attribute[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#get-beta-v1-org-org_id-commitment-plans-plan_id-covered-resources-attributes-field) get/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/covered-resources/attributes/{field} Returns the distinct values for a given field, restricted to the resources the plan covers (and further narrowed by any search/filter passed). Use to discover valid filter values without paginating through the covered-resources list. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired fieldstring · min: 1Required Query parameters line\_item\_idsstring · uuid\[\] · nullableOptional Filter to matches from specific line items Default: `null` only\_selected\_line\_itemsbooleanOptional Only include matches from selected line items (default true) Default: `true` searchstring · nullableOptional Free-text ILIKE search across the resource SKU's identity and classification fields (resource id, name, account ids, service, region, instance\_type, etc.). Mirrors the search lane on /resources/skus. Default: `null` filterobject · nullableOptional JSON filter object — same {field, op, value} tree accepted by /resources/skus. Filterable on the resource SKU side: identity, tags (`has` with nested key/value filters), SKU classification, and the trailing-30-day spend/usage aggregates: `total_cost`, `ondemand_cost`, `gross_savings` (TOTAL summed over the trailing 30 days, NOT a monthly rate — same basis as /resources/skus), `coverage` (spend-based fraction covered by ALL existing commitments — current actuals, NOT this plan's projected coverage; that's the response's per-match `projected_coverage`), and `uptime` (fraction). All warehouse aggregates here are actuals across existing commitments, NOT plan-scoped projections. Call /covered-resources/attributes for the full filterable surface. Default: `null` Show properties order\_bystring · enumOptional Field to order results by. Defaults to monthly\_net\_savings. All numeric axes are 730-hour monthly rates on the per-match plan economics, net of the Archera premium where applicable (NOT the resource's warehouse trailing-30-day actuals — those are filterable but not orderable here, on purpose, to keep sort and response framing on the same monthly basis). Default: `monthly_net_savings`Possible values: `id``projected_coverage``monthly_net_savings``monthly_before_cost``monthly_after_cost``monthly_after_ondemand_cost` descbooleanOptional Sort descending (default true) Default: `true` Responses 200 OK application/json object · BooleanAttributeOptional Show properties or object · UUIDAttributeOptional Show properties or object · StringAttributeOptional Show properties or object · IntegerAttributeOptional Show properties or object · FloatAttributeOptional Show properties or object · CurrencyAttributeOptional Show properties or object · PercentAttributeOptional Show properties or object · DateTimeAttributeOptional Show properties or object · DateAttributeOptional Show properties or object · TimeAttributeOptional Show properties or object · EnumAttributeOptional Show properties or object · TagsAttributeOptional Show properties 400 Bad request application/json 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}/commitment-plans/{plan\_id}/covered-resources/attributes/{field} HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/attributes/{field} HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ``` { "name": "text", "field": "text", "type": "boolean", "filters": [\ {\ "field": "text",\ "value": "text",\ "op": "="\ }\ ] } ``` ### Aggregated covered-resources summary for a commitment plan[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#get-beta-v1-org-org_id-commitment-plans-plan_id-covered-resources-summary) get/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/covered-resources/summary Returns the resources a commitment plan covers, aggregated by (service, account, region, resource\_type). Each row is one group: rolled-up costs, savings, spend-weighted coverage, and resource count. Sorted by net savings descending. For per-resource detail, use the paginated /covered-resources endpoint. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Query parameters line\_item\_idsstring · uuid\[\] · nullableOptional Filter to matches from specific line items Default: `null` only\_selected\_line\_itemsbooleanOptional Only include matches from selected line items (default true) Default: `true` Responses 200 OK application/json servicestring · nullableOptional Cloud service name (e.g. 'AmazonEC2', 'AmazonRDS') account\_idstring · nullableOptional Cloud account ID regionstring · nullableOptional Cloud region (e.g. 'us-east-1') resource\_typestring · nullableOptional Resource type within this group — instance family for compute (e.g. 'm5'), usage type for other services (e.g. 'Fargate-GB-Hours', 'Lambda-GB-Second'), or SKU name as fallback resource\_countintegerOptional Number of resources in this group projected\_coveragenumberOptional Spend-based projected coverage across resources in this group (0-1), weighted by each resource's on-demand-equivalent cost. Distinct from `resource.coverage` (trailing-30-day actual spend-based coverage from existing commitments). For per-resource projected coverage, use the paginated /covered-resources endpoint. commitment\_financials\_monthly\_rateobject · CommitmentFinancialsNoRebateOptional Show properties 400 Bad request application/json 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}/commitment-plans/{plan\_id}/covered-resources/summary HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources/summary HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ``` [\ {\ "service": "text",\ "account_id": "text",\ "region": "text",\ "resource_type": "text",\ "resource_count": 1,\ "projected_coverage": 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\ }\ }\ ] ``` ### Paginated covered resources for a commitment plan[Direct link to heading](https://docs.archera.ai/api-reference/beta-api/commitment-plans-beta\#get-beta-v1-org-org_id-commitment-plans-plan_id-covered-resources) get/beta/v1/org/{org\_id}/commitment-plans/{plan\_id}/covered-resources Returns one row per resource the plan covers, with the plan's economics scoped to that resource (coverage, monthly savings, before/after cost) and full ResourceSKU detail. Supports search, structured filter, sort, and cursor pagination — same surface idiom as /resources/skus, but scoped to the plan's matched resources. Use /covered-resources/summary for the aggregated breakdown. `X-Pagination` is navigation-only: it always includes `page` and `first_page`, and adds `previous_page` and `next_page` when available. GitBook Assistant Path parameters org\_idstring · uuidRequired plan\_idstring · uuidRequired Query parameters line\_item\_idsstring · uuid\[\] · nullableOptional Filter to matches from specific line items Default: `null` only\_selected\_line\_itemsbooleanOptional Only include matches from selected line items (default true) Default: `true` searchstring · nullableOptional Default: `null` filterobject · nullableOptional Default: `null` Show properties order\_bystring · enumOptional descbooleanOptional Sort descending (default true) Default: `true` pageinteger · min: 1OptionalDefault: `1` page\_sizeinteger · min: 1 · max: 100OptionalDefault: `20` Responses 200 OK application/json Headersobject Show Header Responseobject · ResourceMatchDetail\[\] Show properties 400 Bad request application/json 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}/commitment-plans/{plan\_id}/covered-resources HTTP HTTPcURLJavaScriptPython GitBook AssistantAskCopy ``` GET /beta/v1/org/{org_id}/commitment-plans/{plan_id}/covered-resources HTTP/1.1 Accept: */* ``` 200 OK GitBook AssistantAskCopy ``` [\ {\ "id": "123e4567-e89b-12d3-a456-426614174000",\ "line_item_id": "123e4567-e89b-12d3-a456-426614174000",\ "projected_coverage": 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\ },\ "resource": {\ "id": "text",\ "resource_id": "123e4567-e89b-12d3-a456-426614174000",\ "catalog_sku_id": "123e4567-e89b-12d3-a456-426614174000",\ "catalog_sku_org_id": "text",\ "provider": "aws",\ "provider_resource_id": "text",\ "provider_sku_id": "text",\ "name": "text",\ "sku_name": "text",\ "integration_id": "text",\ "billing_account_id": "text",\ "sub_account_id": "text",\ "resource_group": "text",\ "is_spot": true,\ "availability_zone": "text",\ "service": "text",\ "provider_service": "text",\ "family": "text",\ "region_code": "text",\ "full_region_name": "text",\ "instance_type": "text",\ "instance_type_family": "text",\ "usage_type": "text",\ "operation": "text",\ "operating_system": "text",\ "tenancy": "text",\ "database_engine": "text",\ "database_edition": "text",\ "cache_engine": "text",\ "is_multi_az": true,\ "is_current_generation": true,\ "license_model": "text",\ "pre_installed_sw": "text",\ "processor_architecture": "text",\ "is_reservable": true,\ "is_byol": true,\ "is_flexible": true,\ "is_serverless": true,\ "vcpu": 1,\ "memory": 1,\ "ondemand_usage_unit": "text",\ "ondemand_usage_price": 1,\ "price_currency": "text",\ "usage_start": "2026-07-27T19:35:56.493Z",\ "usage_end": "2026-07-27T19:35:56.493Z",\ "tags": {\ "ANY_ADDITIONAL_PROPERTY": "text"\ }\ }\ }\ ] ``` [PreviousAllocation Reports (Beta)](https://docs.archera.ai/api-reference/beta-api/allocation-reports-beta) [NextCommitment Plan Templates (Beta)](https://docs.archera.ai/api-reference/beta-api/commitment-plan-templates-beta) Last updated 10 days ago Was this helpful? This site uses cookies to deliver its service and to analyze traffic. By browsing this site, you accept the [privacy policy](https://app.archera.ai/documents/privacy.pdf). AcceptReject