---
title: "List AWS planned purchases"
method: GET
path: "/ps4commitments/v1/aws/payer-accounts/{payerAccountId}/planned-purchases"
tags: ["PS4Commitments AWS"]
---

# List AWS planned purchases

`GET /ps4commitments/v1/aws/payer-accounts/{payerAccountId}/planned-purchases`

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`.

## Path parameters

- `payerAccountId` string, required

## Query parameters

- `service` 'compute' | 'database'
- `pageToken` string
- `maxResults` integer

## Headers

- `X-Tenant-Id` string

## Response `200`

Paginated list of planned purchase projections.

- object
  - `items` AwsPlannedPurchase[], required
    - `payerAccountId` string, required — 12-digit AWS Master Payer Account ID.
    - `service` 'compute' | 'database', required — PS4C product line this projection belongs to.
    - `status` 'valid' | 'expired', required — 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`.
    - `purchaseApprovalStatus` 'pending_approval' | 'approved' | 'paused' — Customer commitment approval state for this product line. Absent or unrecognized stored values are returned as `pending_approval`.
    - `pauseNote` string, nullable — Customer-visible pause reason, when purchases are paused.
    - `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.
    - `wowViolation` boolean — `true` when week-over-week eligible spend dropped beyond the allowed threshold.
    - `profile` 'conservative' | 'balanced' | 'max_savings' — Coverage target policy. - `conservative` — lower coverage target (~65%) - `balanced` — moderate coverage target (~80%) - `max_savings` — aggressive coverage target (~90%)
    - `term` 'one_year' | 'three_year' — Commitment term length.
    - `paymentOption` 'no_upfront' | 'partial_upfront' | 'all_upfront' | 'null', nullable
    - `finalCommitment` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `weeksToTarget` integer, nullable — Number of ladder steps remaining to reach the target commitment.
    - `planningCycleStartDate` string, date, nullable
    - `planningCycleEndDate` string, date, nullable
    - `estimatedSavings` Money
      - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
      - `currency` string, required — ISO 4217 currency code.
    - `steps` AwsPurchasePlanStep[] — Weekly ladder steps from the projection output. Omitted when the stored document has no `output` section.
      - `order` integer, required — Step sequence number (1-based).
      - `scheduledDate` string, date, required
      - `purchaseAmount` Money, required
        - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
        - `currency` string, required — ISO 4217 currency code.
      - `cumulativeCommitment` Money, required
        - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
        - `currency` string, required — ISO 4217 currency code.
      - `estimatedSavings` Money, required
        - `amount` string, required — Decimal monetary amount at ISO 4217 minor-unit precision (string).
        - `currency` string, required — ISO 4217 currency code.
      - `isBootstrap` boolean, required — `true` if this is the initial bootstrap purchase.
      - `isFinal` boolean, required — `true` if this step reaches the target commitment.
      - `requiresApproval` boolean, required — `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, nullable
  - `rowCount` integer, required — Number of items in `items` for this response.

## Other responses

- `400` — Syntactically malformed request, missing required parameter, or unsupported parameter value.
- `401` — Missing or invalid credentials.
- `403` — Authenticated but not authorised to access this customer's PS4C resources.
- `404` — The requested resource does not exist.
- `500` — Unexpected server error.
- `503` — Service temporarily unavailable; retry after the indicated delay.

---

[API](https://skmtc.dev/doit/apis/doit-cloud-intelligence.md) · [All operations](https://skmtc.dev/doit/apis/doit-cloud-intelligence/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/doit/doit-cloud-intelligence/revisions/9416402fc119/schema)