list-aws-planned-purchases
dci list-aws-planned-purchases <managementAccountId> [flags]
Returns planned purchases (laddering projections) for the AWS organization. One item per commitment type that has a projection available (typically compute and/or database; up to four commitment types as PerfectScale for Commitments expands).
With no filters, returns all available planned-purchase items for the AWS organization in stable commitment-type order (compute, then database, then any future commitment types in enum order). When a filtered commitment type has no planned purchases, the response is an empty items array (not 404). Partial items return only the fields available at response time.
404 is returned only when the AWS organization does not exist or the caller cannot access it. An AWS organization that is not onboarded for PerfectScale for Commitments still returns 200 with an empty items array when no planned purchases exist — use GET /ps4commitments/v1/aws/organizations (or get-by-id) for onboardingStatus.
Pagination: results are returned in stable commitment-type order (compute, then database, then any future commitment types in enum order). Use maxResults to limit page size (default 50, max 500). When more items remain, the response includes a non-null pageToken; pass it unchanged on the next request with the same query parameters (service, maxResults). rowCount is the number of items in this page. An invalid pageToken returns 400 with code pagination_token_invalid; an expired token returns 400 with code pagination_token_expired.
managementAccountId— 12-digit AWS management (payer) account ID (the account that owns the AWS Organization) that scopes the request.
An organization with no planned purchases (including one not yet onboarded) returns an
empty list, not an error; 404 only means the organization does not exist or you
cannot access it. Check onboardingStatus with get-aws-organization. --service
accepts compute or database.
Examples
# Planned commitment purchases (laddering projections), one item per commitment type with a projection.
dci list-aws-planned-purchases <management-account-id>
# Only the compute projection.
dci list-aws-planned-purchases <management-account-id> --service compute
# The full projections as JSON, including the ladder `steps`, for scripts.
dci list-aws-planned-purchases <management-account-id> --output json
Flags
| Flag | Type | Default | Example | Description |
|---|---|---|---|---|
--service | string | Filter planned purchases by PerfectScale for Commitments commitment type. Omit to return all commitment types that have planned purchases for the AWS organization. One of: "compute", "database". | ||
--page-token | string | Opaque cursor token returned by a previous list response. Omit to start from the beginning; an empty or absent token in a response means there are no more results. Do not parse it. A structurally invalid cursor returns 400 with code pagination_token_invalid; an expired cursor returns 400 with code pagination_token_expired — restart pagination from the beginning. | ||
--max-results | integer | 50 | Maximum number of items to return. Server may return fewer. Defaults to 50; maximum 500. |
Every command also accepts the CLI-wide flags for output shaping — see Output formats and Table output options.
Output
Paginated list of planned purchase projections.
By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.
| Field | Type | Description |
|---|---|---|
items | array of object | |
items[].managementAccountId | string | 12-digit account number of the AWS organization's management (payer) account. |
items[].service | string | Commitment type this projection belongs to (compute or database). One of: "compute", "database". |
items[].status | string | Projection lifecycle state. expired means the planning cycle has lapsed and a new projection should be triggered by the automated scheduler. When the stored document has no status, the server returns valid. One of: "valid", "expired". |
items[].purchaseApprovalStatus | string | Approval state for purchases of this commitment type. Approve or pause on the Planned Purchases tab in the DoiT Console. Absent or unrecognized stored values are returned as pending_approval, except on autonomous automation-mode lines, where they are returned as approved since no customer approval is required. One of: "pending_approval", "approved", "paused". |
items[].pauseNote | string | Customer-visible pause reason when purchaseApprovalStatus is paused. Null when purchases are not paused. |
items[].requiresApproval | boolean | true when the projection as a whole requires customer approval before the planner stores a purchase plan: the target finalCommitment exceeds the approved ceiling, and/or purchaseApprovalStatus is not approved. Distinct from step-level steps[].requiresApproval, which flags individual ladder rows that exceed the ceiling. |
items[].wowViolation | boolean | true when week-over-week eligible spend dropped beyond the allowed threshold. |
items[].profile | string | Coverage target policy used to generate this projection. |
items[].term | string | Commitment term used for projected purchases. |
items[].paymentOption | string | Payment structure for projected purchases. May be null when not set on the stored projection. One of: "no_upfront", "partial_upfront", "all_upfront", null. |
items[].finalCommitment | object | Target hourly commitment at the end of the laddering cycle. Currency is USD. |
items[].finalCommitment.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].finalCommitment.currency | string | ISO 4217 currency code. |
items[].weeksToTarget | integer | Number of ladder steps remaining to reach the target commitment. |
items[].planningCycleStartDate | string (date) | First day of the planning cycle for this projection. Null when not set. |
items[].planningCycleEndDate | string (date) | Last day of the planning cycle for this projection. Null when not set. |
items[].estimatedSavings | object | Total estimated savings from the underlying recommendation. Currency is USD. |
items[].estimatedSavings.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].estimatedSavings.currency | string | ISO 4217 currency code. |
items[].steps | array of object | Weekly ladder steps from the projection output. Omitted when the stored document has no output section. |
items[].steps[].order | integer | Step sequence number (1-based) within the ladder. |
items[].steps[].scheduledDate | string (date) | Calendar date (UTC) when this purchase step is scheduled to execute, with format YYYY-MM-DD. |
items[].steps[].purchaseAmount | object | Hourly commitment to purchase on this step. |
items[].steps[].purchaseAmount.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].steps[].purchaseAmount.currency | string | ISO 4217 currency code. |
items[].steps[].cumulativeCommitment | object | Total hourly commitment after this step executes. |
items[].steps[].cumulativeCommitment.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].steps[].cumulativeCommitment.currency | string | ISO 4217 currency code. |
items[].steps[].estimatedSavings | object | This step's proportional share of the projection-level estimatedSavings (allocated by purchase amount). Zero when the recommendation total is unavailable. |
items[].steps[].estimatedSavings.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].steps[].estimatedSavings.currency | string | ISO 4217 currency code. |
items[].steps[].isBootstrap | boolean | true if this is the initial bootstrap purchase. |
items[].steps[].isFinal | boolean | true if this step reaches the target commitment. |
items[].steps[].requiresApproval | boolean | true when this step's cumulativeCommitment exceeds the customer-approved commitment ceiling (approvedFinalCommitment). Used for per-step status in the ladder even when the projection-level purchaseApprovalStatus is approved. |
pageToken | string | |
rowCount | integer (int64) | Number of items in items for this response. |
Raw JSON schema
{
"type": "object",
"required": [
"items",
"rowCount"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"managementAccountId",
"service",
"status"
],
"properties": {
"managementAccountId": {
"type": "string",
"description": "12-digit account number of the AWS organization's management (payer) account."
},
"service": {
"type": "string",
"enum": [
"compute",
"database"
],
"description": "Commitment type this projection belongs to (`compute` or `database`).",
"x-enumDescriptions": {
"compute": "Compute commitment type (Savings Plans).",
"database": "Database commitment type (Savings Plans)."
}
},
"status": {
"type": "string",
"enum": [
"valid",
"expired"
],
"description": "Projection lifecycle state. `expired` means the planning cycle has lapsed and a new projection should be triggered by the automated scheduler. When the stored document has no `status`, the server returns `valid`.",
"x-enumDescriptions": {
"valid": "Projection is current for the active planning cycle.",
"expired": "Planning cycle has lapsed; wait for the scheduler to produce a new projection."
}
},
"purchaseApprovalStatus": {
"type": "string",
"enum": [
"pending_approval",
"approved",
"paused"
],
"description": "Approval state for purchases of this commitment type. Approve or pause on the Planned Purchases tab in the DoiT Console. Absent or unrecognized stored values are returned as `pending_approval`, except on autonomous automation-mode lines, where they are returned as `approved` since no customer approval is required.",
"x-enumDescriptions": {
"pending_approval": "Approve the commitment ceiling on the Planned Purchases tab in the DoiT Console before purchases can run.",
"approved": "Purchases may run up to the approved commitment ceiling.",
"paused": "Purchases are paused (Pause Purchases on Planned Purchases); see `pauseNote` for the reason."
}
},
"pauseNote": {
"type": "string",
"description": "Customer-visible pause reason when `purchaseApprovalStatus` is `paused`. Null when purchases are not paused.",
"nullable": true
},
"requiresApproval": {
"type": "boolean",
"description": "`true` when the projection as a whole requires customer approval before the planner stores a purchase plan: the target `finalCommitment` exceeds the approved ceiling, and/or `purchaseApprovalStatus` is not `approved`. Distinct from step-level `steps[].requiresApproval`, which flags individual ladder rows that exceed the ceiling."
},
"wowViolation": {
"type": "boolean",
"description": "`true` when week-over-week eligible spend dropped beyond the allowed threshold."
},
"profile": {
"allOf": [
{
"type": "string",
"enum": [
"conservative",
"balanced",
"max_savings"
],
"description": "Coverage target policy that balances savings against underutilization risk. Used by recommendations and planned-purchase projections.",
"x-enumDescriptions": {
"conservative": "Lower coverage target (~65%); favors stable usage and lower underutilization risk.",
"balanced": "Moderate coverage target (~80%); default balance of savings and buffer.",
"max_savings": "Aggressive coverage target (~90%); highest savings potential with a smaller buffer."
}
}
],
"description": "Coverage target policy used to generate this projection."
},
"term": {
"allOf": [
{
"type": "string",
"enum": [
"one_year",
"three_year"
],
"description": "Preferred or actual commitment term length for Savings Plans and related settings.",
"x-enumDescriptions": {
"one_year": "One-year commitment term.",
"three_year": "Three-year commitment term."
}
}
],
"description": "Commitment term used for projected purchases."
},
"paymentOption": {
"type": "string",
"enum": [
"no_upfront",
"partial_upfront",
"all_upfront",
null
],
"nullable": true,
"description": "Payment structure for projected purchases. May be null when not set on the stored projection.",
"x-enumDescriptions": {
"no_upfront": "All charges paid monthly; no upfront payment.",
"partial_upfront": "A portion paid upfront; remainder billed monthly.",
"all_upfront": "Full commitment paid upfront."
}
},
"finalCommitment": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "Target hourly commitment at the end of the laddering cycle. Currency is `USD`."
},
"weeksToTarget": {
"type": "integer",
"description": "Number of ladder steps remaining to reach the target commitment.",
"nullable": true
},
"planningCycleStartDate": {
"type": "string",
"format": "date",
"description": "First day of the planning cycle for this projection. Null when not set.",
"nullable": true
},
"planningCycleEndDate": {
"type": "string",
"format": "date",
"description": "Last day of the planning cycle for this projection. Null when not set.",
"nullable": true
},
"estimatedSavings": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "Total estimated savings from the underlying recommendation. Currency is `USD`."
},
"steps": {
"type": "array",
"items": {
"type": "object",
"description": "A single weekly ladder step within a projection.",
"required": [
"order",
"scheduledDate",
"purchaseAmount",
"cumulativeCommitment",
"estimatedSavings",
"isBootstrap",
"isFinal",
"requiresApproval"
],
"properties": {
"order": {
"type": "integer",
"description": "Step sequence number (1-based) within the ladder."
},
"scheduledDate": {
"type": "string",
"format": "date",
"description": "Calendar date (UTC) when this purchase step is scheduled to execute, with format YYYY-MM-DD."
},
"purchaseAmount": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "Hourly commitment to purchase on this step."
},
"cumulativeCommitment": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "Total hourly commitment after this step executes."
},
"estimatedSavings": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "This step's proportional share of the projection-level `estimatedSavings` (allocated by purchase amount). Zero when the recommendation total is unavailable."
},
"isBootstrap": {
"type": "boolean",
"description": "`true` if this is the initial bootstrap purchase."
},
"isFinal": {
"type": "boolean",
"description": "`true` if this step reaches the target commitment."
},
"requiresApproval": {
"type": "boolean",
"description": "`true` when this step's `cumulativeCommitment` exceeds the customer-approved commitment ceiling (`approvedFinalCommitment`). Used for per-step status in the ladder even when the projection-level `purchaseApprovalStatus` is `approved`."
}
}
},
"description": "Weekly ladder steps from the projection output. Omitted when the stored document has no `output` section."
}
}
}
},
"pageToken": {
"type": "string",
"nullable": true
},
"rowCount": {
"type": "integer",
"format": "int64",
"description": "Number of items in `items` for this response."
}
}
}
Errors
On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.
HTTP status to exit code mapping
| HTTP status | Exit code | Error code | Meaning |
|---|---|---|---|
| 400 | 30 | VALIDATION_ERROR | The arguments or request body were rejected. Review the command's flags and payload. |
| 401 | 10 | AUTHENTICATION_FAILED | Not signed in, or the API token is invalid. Run dci login or check DCI_API_KEY. |
| 403 | 11 | PERMISSION_DENIED | The DoiT user or the active customer context does not have access. |
| 404 | 20 | RESOURCE_NOT_FOUND | The requested resource does not exist. Check the identifier argument. |
| 500, 503 | 40 | API_SERVER_ERROR | The API failed to process the request. Retryable; contact DoiT support if it persists. |
Related
- list-aws-recommendations — List AWS recommendations
- get-aws-recommendation — Get an AWS recommendation
- get-aws-organization — Get an AWS organization
- list-aws-organizations-settings — List account and commitment settings per AWS organization
- API reference: GET /ps4commitments/v1/aws/organizations/{managementAccountId}/planned-purchases
Aliases: listawsplannedpurchases