list-aws-planned-purchases
dci list-aws-planned-purchases payerAccountId [flags]
Returns the laddering projections for the MPA — one item per available
purchases-projection document (typically compute and/or database; up to four
product lines as PS4C expands).
With no filters, returns all existing projection documents for the payer account in
stable product-line order (compute, then database, then any future lines in enum
order). When a filtered product line has no projection document, the response is an
empty items array (not 404). Partial projection documents return only the fields
available in storage.
404 is returned only when the payer account does not exist or the caller cannot
access it. A payer account that is not onboarded for PS4C still returns 200 with an
empty items array when no projection documents exist — use
GET /ps4commitments/v1/aws/payer-accounts (or get-by-id) for onboardingStatus.
Pagination: results are returned in stable product-line order (compute, then
database, then any future lines 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.
Flags
--service: (string enum:"compute","database")
--page-token: (string)
--max-results: (integer default:50)
Responses
200 (application/json)
Paginated list of planned purchase projections.
{
"type": "object",
"required": [
"items",
"rowCount"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"payerAccountId",
"service",
"status"
],
"properties": {
"payerAccountId": {
"type": "string",
"description": "12-digit AWS Master Payer Account ID."
},
"service": {
"type": "string",
"enum": [
"compute",
"database"
],
"description": "PS4C product line this projection belongs to."
},
"status": {
"type": "string",
"enum": [
"valid",
"expired"
],
"description": "Projection lifecycle state. `expired` means the planning cycle has lapsed and a\nnew projection should be triggered by the automated scheduler. When the stored\ndocument has no `status`, the server returns `valid`."
},
"purchaseApprovalStatus": {
"type": "string",
"enum": [
"pending_approval",
"approved",
"paused"
],
"description": "Customer commitment approval state for this product line. Absent or unrecognized\nstored values are returned as `pending_approval`."
},
"pauseNote": {
"type": "string",
"description": "Customer-visible pause reason, when purchases are paused.",
"nullable": true
},
"requiresApproval": {
"type": "boolean",
"description": "`true` when the projection as a whole requires customer approval before the planner\nstores a purchase plan: the target `finalCommitment` exceeds the approved ceiling,\nand/or `purchaseApprovalStatus` is not `approved`. Distinct from step-level\n`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": {
"type": "string",
"enum": [
"conservative",
"balanced",
"max_savings"
],
"description": "Coverage target policy.\n- `conservative` — lower coverage target (~65%)\n- `balanced` — moderate coverage target (~80%)\n- `max_savings` — aggressive coverage target (~90%)\n"
},
"term": {
"type": "string",
"enum": [
"one_year",
"three_year"
],
"description": "Commitment term length."
},
"paymentOption": {
"type": "string",
"enum": [
"no_upfront",
"partial_upfront",
"all_upfront",
null
],
"nullable": true
},
"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)."
},
"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` in v1."
},
"weeksToTarget": {
"type": "integer",
"description": "Number of ladder steps remaining to reach the target commitment.",
"nullable": true
},
"planningCycleStartDate": {
"type": "string",
"format": "date",
"nullable": true
},
"planningCycleEndDate": {
"type": "string",
"format": "date",
"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)."
},
"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` in v1."
},
"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)."
},
"scheduledDate": {
"type": "string",
"format": "date"
},
"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)."
},
"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)."
},
"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)."
},
"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`\n(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\ncommitment ceiling (`approvedFinalCommitment`). Used for per-step status in the\nladder even when the projection-level `purchaseApprovalStatus` is `approved`."
}
}
},
"description": "Weekly ladder steps from the projection output. Omitted when the stored document has\nno `output` section."
}
}
}
},
"pageToken": {
"type": "string",
"nullable": true
},
"rowCount": {
"type": "integer",
"format": "int64",
"description": "Number of items in `items` for this response."
}
}
}
400 (application/problem+json)
Syntactically malformed request, missing required parameter, or unsupported parameter value.
{
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"instance",
"code",
"retryable"
],
"additionalProperties": true,
"description": "RFC 9457 Problem Details — standard DoiT error envelope for all non-2xx responses.",
"properties": {
"type": {
"type": "string",
"format": "uri",
"example": "https://developer.doit.com/errors/not_found"
},
"title": {
"type": "string",
"example": "Resource not found"
},
"status": {
"type": "integer",
"example": 404
},
"detail": {
"type": "string",
"example": "customer not found"
},
"instance": {
"type": "string",
"format": "uri",
"example": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9"
},
"code": {
"type": "string",
"pattern": "^([a-z][a-z0-9_]*|[a-z][a-z0-9]*(?:-[a-z0-9]+)*\\.[a-z][a-z0-9_]*)$",
"example": "not_found"
},
"retryable": {
"type": "boolean",
"example": false
},
"details": {
"type": "array",
"items": {
"type": "object",
"required": [
"issue"
],
"properties": {
"issue": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"field": {
"type": "string"
}
},
"additionalProperties": true
}
},
"docsUrl": {
"type": "string",
"format": "uri"
}
}
}
401 (application/problem+json)
Missing or invalid credentials.
{
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"instance",
"code",
"retryable"
],
"additionalProperties": true,
"description": "RFC 9457 Problem Details — standard DoiT error envelope for all non-2xx responses.",
"properties": {
"type": {
"type": "string",
"format": "uri",
"example": "https://developer.doit.com/errors/not_found"
},
"title": {
"type": "string",
"example": "Resource not found"
},
"status": {
"type": "integer",
"example": 404
},
"detail": {
"type": "string",
"example": "customer not found"
},
"instance": {
"type": "string",
"format": "uri",
"example": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9"
},
"code": {
"type": "string",
"pattern": "^([a-z][a-z0-9_]*|[a-z][a-z0-9]*(?:-[a-z0-9]+)*\\.[a-z][a-z0-9_]*)$",
"example": "not_found"
},
"retryable": {
"type": "boolean",
"example": false
},
"details": {
"type": "array",
"items": {
"type": "object",
"required": [
"issue"
],
"properties": {
"issue": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"field": {
"type": "string"
}
},
"additionalProperties": true
}
},
"docsUrl": {
"type": "string",
"format": "uri"
}
}
}
403 (application/problem+json)
Authenticated but not authorised to access this customer's PS4C resources.
{
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"instance",
"code",
"retryable"
],
"additionalProperties": true,
"description": "RFC 9457 Problem Details — standard DoiT error envelope for all non-2xx responses.",
"properties": {
"type": {
"type": "string",
"format": "uri",
"example": "https://developer.doit.com/errors/not_found"
},
"title": {
"type": "string",
"example": "Resource not found"
},
"status": {
"type": "integer",
"example": 404
},
"detail": {
"type": "string",
"example": "customer not found"
},
"instance": {
"type": "string",
"format": "uri",
"example": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9"
},
"code": {
"type": "string",
"pattern": "^([a-z][a-z0-9_]*|[a-z][a-z0-9]*(?:-[a-z0-9]+)*\\.[a-z][a-z0-9_]*)$",
"example": "not_found"
},
"retryable": {
"type": "boolean",
"example": false
},
"details": {
"type": "array",
"items": {
"type": "object",
"required": [
"issue"
],
"properties": {
"issue": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"field": {
"type": "string"
}
},
"additionalProperties": true
}
},
"docsUrl": {
"type": "string",
"format": "uri"
}
}
}
404 (application/problem+json)
The requested resource does not exist.
{
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"instance",
"code",
"retryable"
],
"additionalProperties": true,
"description": "RFC 9457 Problem Details — standard DoiT error envelope for all non-2xx responses.",
"properties": {
"type": {
"type": "string",
"format": "uri",
"example": "https://developer.doit.com/errors/not_found"
},
"title": {
"type": "string",
"example": "Resource not found"
},
"status": {
"type": "integer",
"example": 404
},
"detail": {
"type": "string",
"example": "customer not found"
},
"instance": {
"type": "string",
"format": "uri",
"example": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9"
},
"code": {
"type": "string",
"pattern": "^([a-z][a-z0-9_]*|[a-z][a-z0-9]*(?:-[a-z0-9]+)*\\.[a-z][a-z0-9_]*)$",
"example": "not_found"
},
"retryable": {
"type": "boolean",
"example": false
},
"details": {
"type": "array",
"items": {
"type": "object",
"required": [
"issue"
],
"properties": {
"issue": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"field": {
"type": "string"
}
},
"additionalProperties": true
}
},
"docsUrl": {
"type": "string",
"format": "uri"
}
}
}
500 (application/problem+json)
Unexpected server error.
{
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"instance",
"code",
"retryable"
],
"additionalProperties": true,
"description": "RFC 9457 Problem Details — standard DoiT error envelope for all non-2xx responses.",
"properties": {
"type": {
"type": "string",
"format": "uri",
"example": "https://developer.doit.com/errors/not_found"
},
"title": {
"type": "string",
"example": "Resource not found"
},
"status": {
"type": "integer",
"example": 404
},
"detail": {
"type": "string",
"example": "customer not found"
},
"instance": {
"type": "string",
"format": "uri",
"example": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9"
},
"code": {
"type": "string",
"pattern": "^([a-z][a-z0-9_]*|[a-z][a-z0-9]*(?:-[a-z0-9]+)*\\.[a-z][a-z0-9_]*)$",
"example": "not_found"
},
"retryable": {
"type": "boolean",
"example": false
},
"details": {
"type": "array",
"items": {
"type": "object",
"required": [
"issue"
],
"properties": {
"issue": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"field": {
"type": "string"
}
},
"additionalProperties": true
}
},
"docsUrl": {
"type": "string",
"format": "uri"
}
}
}
503 (application/problem+json)
Service temporarily unavailable; retry after the indicated delay.
{
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"instance",
"code",
"retryable"
],
"additionalProperties": true,
"description": "RFC 9457 Problem Details — standard DoiT error envelope for all non-2xx responses.",
"properties": {
"type": {
"type": "string",
"format": "uri",
"example": "https://developer.doit.com/errors/not_found"
},
"title": {
"type": "string",
"example": "Resource not found"
},
"status": {
"type": "integer",
"example": 404
},
"detail": {
"type": "string",
"example": "customer not found"
},
"instance": {
"type": "string",
"format": "uri",
"example": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9"
},
"code": {
"type": "string",
"pattern": "^([a-z][a-z0-9_]*|[a-z][a-z0-9]*(?:-[a-z0-9]+)*\\.[a-z][a-z0-9_]*)$",
"example": "not_found"
},
"retryable": {
"type": "boolean",
"example": false
},
"details": {
"type": "array",
"items": {
"type": "object",
"required": [
"issue"
],
"properties": {
"issue": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"field": {
"type": "string"
}
},
"additionalProperties": true
}
},
"docsUrl": {
"type": "string",
"format": "uri"
}
}
}
Aliases: list-aws-planned-purchases, listawsplannedpurchases