APX Interface Specification · APX Specification · APX 0.16.0 · OpenAPI 0.16.0 · built on APDS 4.1 (2026-01-14) · Draft

Interface Specification

APX Specification: technical documentation

Version 0.16.0 (draft)

Updated 2026-11-02

APX Specification · APX 0.16.0 · OpenAPI 0.16.0 · built on APDS 4.1 (2026-01-14) · Draft

Introduction

The APDS 4.1 set gives its interface as an OpenAPI document, apds-api-4.1.yaml, alongside the Overview, Information Model, Data Dictionary and Use Case Document. APX does the same: the normative interface is spec/dist/apx-v1.yaml (OpenAPI 3.1). This document is a readable listing of that file, generated from it each time the documents are built. Where the two differ, the OpenAPI document wins.

The data elements the operations carry are defined in 03 Data Dictionary. The rules for using them are in the APX standard text, Parts 0 to 24 (docs/standard/).

Two surfaces on one host

One host serves both surfaces:

• APDS 4.1 native routes at their published paths (/places, /sessions, /webhooks and so on). APX carries them unchanged, apart from the corrections listed in 06, Part A, and adds only optional parameters such as the change-feed mode and cursor (Part 5 §5.2).
• APX routes under the /v1 prefix.

The "Origin" row in each operation says which surface it belongs to.

Conventions that apply to every operation

How to read an operation

Each operation has a summary table (operation id, origin, scopes and request body), a parameter table and a response table. Body types name the class in 03 Data Dictionary. Responses that every operation shares, such as 401, 403 and 429, are listed each time so that each operation can be read on its own.

Operations at a glance

The APX OpenAPI document declares 207 operations and 6 webhooks. 40 operations are APDS 4.1 native routes that APX carries; the rest are defined by APX.

1 Start here

1.1 Discovery

Where every integration starts. A partner needs exactly one thing to begin: a hostname.

1.1.1 GET /v1/digest-keys

The keys behind apds-ext:apx:credential-digest@1.0. The digest keys the implementation currently signs credential digests with, so an authorised consumer can compute the digest of a plate it holds and match it to decorated records without ever receiving plates (Part 9 §9.6 rule 6). Rotation is by keyId; both keys are served during an overlap. The normalization the implementation applies before hashing is stated per key.

1.1.2 GET /v1/discovery

Credential-scoped capability document. Reflects the presented token's scopes and grants exactly: the endpoints, command types, topics, and place subtrees THIS client can use. Soundness rule: everything listed is callable; APX endpoints not listed fail with 403.

1.1.3 GET /.well-known/apx-configuration

Bootstrap configuration document. Unauthenticated bootstrap document. Advertises the token endpoint, the APDS version this implementation extends, supported APX conformance classes, and code-list registry locations.

2 Platform

2.1 Data

Reading and writing parking data, and staying in sync.

2.1.1 GET /v1/places/{id}/occupancy

Current occupancy snapshot for a place element. "How full is it right now" for one HierarchyElement, without pulling the Place hierarchy. A pure convenience READ over the APDS occupancy model (Supply + DemandTable) — the Place payload remains the source of truth. Fields the implementation does not know are simply absent. Threshold crossings publish apx.data.occupancy.v1 and SHOULD raise an occupancyThresholdExceeded alert (Part 7). Scope apx.data:read; the place grant must cover the element.

2.1.2 GET /v1/places/{id}/occupancy/history

Occupancy per clock interval for one element. The history behind the §5.5 snapshot (Part 5 §5.5a), derived from the APDS DemandTable records the implementation holds for the element. Buckets align to interval boundaries in the place's time zone; an element the implementation holds no occupancy for is 404 target-not-found; the apx_places grant must cover the element.

2.2 Subscription

Push instead of poll. A superset-compatible profile of the APDS 4.1 /webhooks endpoint: stock APDS subscription bodies work here unmodified.

2.2.1 GET /webhooks

List subscriptions (APX additive operation). Lists subscriptions visible to the caller. Secrets are never returned.

2.2.2 POST /webhooks

Subscribe to event topics (APDS-compatible superset). Creates a subscription. A stock APDS 4.1 EventSubscription ({endpoint, topics[]} with EventTypeEnum values) is a valid body; APX fields (transport, filters, secret) are additive.

2.2.3 GET /webhooks/{id}

Read one subscription (APX additive operation). Returns one subscription the caller may see — its status, activeKeyIds, and filters — without paging through GET /webhooks. Secrets are never returned. Readable in every state, including failed (Part 8 §8.1).

2.2.4 PATCH /webhooks/{id}

Update a subscription (APX additive operation). Update topics, endpoint, filters, or status (pause, resume a paused or failed subscription), or rotate the secret. The body is a JSON Merge Patch over the subscription: send only what changes (Part 8 §8.1). The precondition is If-Match or the body version; a stale one is 409 version-conflict (Part 4 §4.2a). While the subscription is failed, the only PATCH accepted is one that sets status: active; any other is 410 subscription-failed.

2.2.5 DELETE /webhooks/{id}

Revoke (delete) existing subscription. Native APDS 4.1 operation, unchanged (APDS ResponseStatus shape).

2.2.6 GET /webhooks/{id}/deliveries

Delivery ledger for a subscription. Returns the delivery records for auditing: one per (event, subscription), with the attempt count, status, last HTTP code, and the per-attempt history (attemptHistory: each attempt's APX-Delivery-Id, time, and code — Part 8 §8.3). Newest first. Readable in every subscription state. An event held while the subscription is paused has no record until its first attempt.

2.2.7 GET /v1/events/stream

Server-Sent Events stream (conformance class apx-events-sse). Streams EventEnvelopes for a subscription with transport: sse. Frame grammar (normative, Part 8 §8.4): one event per frame, an id: line carrying the per-subscription sequence (a decimal integer), a single data: line carrying the envelope JSON, and a blank line; retry: and comment lines MAY appear. Reconnect with Last-Event-ID to resume strictly after that sequence.

2.3 Control

Doing things in the real world. APDS inventories devices and marks access-controlled places but defines no actuation. This is it.

2.3.1 GET /v1/commands

List and filter commands (the audit query). The commands the caller may see, newest first by the time the command was received, each with its full statusHistory (Part 6 §6.1b). Only commands whose target lies inside the token's apx_places grant are returned; naming a place outside the grant is 403 insufficient-grant. All filters combine with AND.

2.3.2 POST /v1/commands

Execute a command (idempotent, perishable, audited). Requests an operational action (vendGate, lostTicket, pushRate, applyValidation, …). Idempotency-Key REQUIRED. Returns 202 with the Command; poll GET /v1/commands/{id} or subscribe to apx.control.command.status.v1. Requires scope apx.control:execute AND a place grant covering the target.

2.3.3 GET /v1/commands/{id}

Read a command (lifecycle + audit trail). Returns the Command including its immutable statusHistory.

2.3.4 POST /v1/commands/{id}/cancel

Cancel a command before dispatch. Allowed in received/accepted states; afterwards 409 command-not-cancellable.

2.3.5 GET /v1/devices

List device status overlays. Live DeviceStatus for every SupplementalEquipment the caller may see, optionally narrowed by place and state (Part 6 §6.4). Naming a place outside the token's apx_places grant is 403 insufficient-grant.

2.3.6 GET /v1/devices/{id}

Read one device's status overlay. DeviceStatus keyed by the SupplementalEquipment id.

2.3.7 GET /v1/lanes/{id}/current

Lane inquiry — current transaction context (screen-pop). The ticket/credential currently in the machine at this lane, amount due, applied validations, latest LPR read, and monthly-credential context including the last 10 activity events. When no ticket is in the machine — or when a lookup parameter is given — also matchCandidates[]: the open sessions at the place that plausibly belong to the vehicle in the lane (Part 6 §6.7), for a driver who has lost the ticket.

2.3.8 GET /v1/validations/providers

List validation providers for a place. The venues allowed to validate tickets at the place.

2.4 Alerts

Knowing something is wrong. A net-new domain: APDS has no alert, event, or notification class.

2.4.1 GET /v1/alerts

List/filter alerts. Filter by status, severityFloor, type, place (subtree-inclusive), device, relatedEntity, since. Alerts with no place binding (e.g. webhookDeliveryFailed) are visible to tokens of the owning organisation and are excluded whenever place is given (Part 7 §7.1).

2.4.2 POST /v1/alerts

Raise an alert (idempotent). Raises an alert. The Idempotency-Key header is REQUIRED: replaying the same key with the same body returns the alert as it currently stands (200, Part 4 §4.2a); the same key with a different body is 409 idempotency-conflict. A client MAY supply id (Part 7 §7.1).

2.4.3 GET /v1/alerts/{id}

Read an alert. Returns the alert including its immutable statusHistory.

2.4.4 POST /v1/alerts/{id}/acknowledge

Acknowledge an alert. Transition raised → acknowledged. Illegal transitions are 409 alert-transition-illegal. The optional body annotates the history entry this transition appends (Part 7 §7.2); a request with no body is unchanged.

2.4.5 POST /v1/alerts/{id}/resolve

Resolve an alert. Transition raised|acknowledged → resolved. Illegal transitions are 409 alert-transition-illegal. The optional body annotates the history entry this transition appends (Part 7 §7.2); a request with no body is unchanged.

2.5 Site configuration

A location, described by APX alone. Before a call, an agent or a system should be able to learn what a site has without data from any other system: which hardware is on each lane and what each piece does, what it is, what runs on it, where the cameras are and what they see, how a parker reaches help from each lane or door, and who to escalate to.

2.5.1 GET /v1/equipment

List a place's equipment with its roles, makes, versions and areas. Every SupplementalEquipment at the place, each with its apds-ext:apx:equipment-detail@1.0 decoration, so a reader learns what the site has from APX alone (Part 26 §26.1). Distinct from GET /v1/devices, which serves live state; this serves the description. mode=change&cursor= serves the Part 5 §5.2 feed, so an edge or call-centre system keeps a local copy current. Naming a place outside the grant is 403 insufficient-grant.

2.5.2 GET /v1/equipment/{id}

Read one piece of equipment. The SupplementalEquipment with its APX decorations (Part 26 §26.1).

2.5.3 GET /v1/comms-points

List or look up comms points. The ways a parker reaches help at the caller's places (Part 26 §26.4). A call platform finds the comms point of an inbound contact with callerId, dialedNumber or commsDeviceId; the answer carries the lane, or the place only. mode=change&cursor= serves the Part 5 §5.2 feed.

2.5.4 POST /v1/comms-points

Add a comms point. Whoever runs the calls adds the comms point, the call centre or the call platform (Part 26 §26.4). place must lie inside the grant (403 insufficient-grant); lane, equipment and serves must exist (422 reference-unknown). Idempotency-Key optional. Publishes apx.commspoints.changed.v1.

2.5.5 GET /v1/comms-points/{id}

Read a comms point. The comms point with the lane or place it serves and the barrier an agent opens for it (Part 26 §26.4).

2.5.6 PUT /v1/comms-points/{id}

Replace a comms point. Full replacement with the version last read as If-Match or body version (409 version-conflict, Part 4 §4.2a). Publishes apx.commspoints.changed.v1.

2.5.7 DELETE /v1/comms-points/{id}

Remove a comms point. The feed emits a tombstone (Part 5 §5.2); publishes apx.commspoints.changed.v1.

2.5.8 POST /v1/identifiers:resolve

Find the APX record behind another system's id. Looks up a {system, id} pair from any apds-ext:apx:external-ids@1.0 decoration the caller may see (Part 26 §26.6), so a PARCS, a call platform or an aggregator goes from its own id to the place, lane, equipment or comms point without a table of its own. A read, as a POST so the id never sits in a URL. No match is 404 target-not-found.

2.5.9 POST /v1/cameras/{id}/views

Get a short-lived link to see a camera. A live stream, a still, or a recording of the camera (the SupplementalEquipment with role camera), as a single-use link bound to the agent and valid for at most 5 minutes (Part 26 §26.3). Whoever holds the camera answers; its password never leaves the site. Every view is logged against the agent and correlationId. Offered under the cameraViews feature; playback also needs cameraPlayback.

2.5.10 GET /v1/display-records

List the messages signs showed. The records that a sign showed a message, newest first (Part 26 §26.9): which sign, which kind of message, when, and for which read or stay. An operator measures the signs with them; an appeal finds the proof of display. mode=change&cursor= serves the Part 5 §5.2 feed. A place outside the grant is 403 insufficient-grant.

2.5.11 POST /v1/display-records

Record that a sign showed a message. Written by whichever system drove the display, the edge controller, the PARCS or the sign's player, usually with no APX command involved (Part 26 §26.9). display must be a SupplementalEquipment (422 reference-unknown); the server derives place from it. No message text and no plate are stored. With command, shownTime and contentHash must agree with that command's CommandResult.display. Immutable once written. Idempotency-Key optional. Publishes apx.displays.shown.v1.

2.5.12 GET /v1/display-records/{id}

Read a display record. What a sign showed, when, and for which read or stay (Part 26 §26.9).

2.6 UI launch

The vendor's own screen, without breaking the record. Most actions in a call centre still happen in a vendor's portal in another window, and the two systems never agree afterwards. A vendor will take years to implement every APX module, but it already has good screens.

2.6.1 GET /v1/ui/launches

List launches. The launch records visible to the caller, newest first (Part 25 §25.3). url is never included on a list read.

2.6.2 POST /v1/ui/launches

Open a vendor screen for an agent (handshake launch). The host sends its normal APX token and gets back a single-use url that logs the named agent into the surface, valid for at most 60 seconds (Part 25 §25.2). This is the launch mode for vendors who want header-based authentication, since a browser cannot add headers when it opens a page. place must lie inside the grant (403 insufficient-grant). Idempotency-Key optional (Part 4 §4.2a). Publishes apx.ui.launch.changed.v1.

2.6.3 GET /v1/ui/launches/{id}

Read a launch and what was done in it. The launch with its actions[] (Part 25 §25.3). url is present only while the launch is issued and before expiresAt.

2.6.4 POST /v1/ui/launches/{id}/actions

Record an action done in the screen (loopback fallback). The surface, or the service behind it, records what the agent did when the implementation could not express it as the module's own resource or Command (Part 25 §25.4). The record carries the launch's correlationId and is published as apx.ui.action.recorded.v1. A launch that was never opened and has expired refuses with ui-launch-expired; a closed one with ui-launch-closed.

2.6.5 POST /v1/ui/launches/{id}/close

Close a launch. The screen reports it is done: opened (or issued) → closed (Part 25 §25.3). No body. Publishes apx.ui.launch.changed.v1. Already closed is 409 ui-launch-closed.

3 Commerce

3.1 Accounts

Money. Account and balance lookup, taking a payment, refunds, voids and captures, accounting write-back, and payment history.

3.1.1 POST /v1/accounts:search

The account lookup with personal data in a body, never a URL. The same lookup as GET /v1/accounts (Part 13 §13.1) with the keys in the body (Part 9 §9.6). Same rules, grant behaviour, and response; a card number pasted into card is 422 personal-data-not-permitted.

3.1.2 POST /v1/payments:search

The payment-history lookup with the keys in a body. The same lookup as GET /v1/payments (Part 13 §13.2) with the keys in the body (Part 9 §9.6). Same keys rule (at least one), 8-hour window on truncated keys, hold rules, grant behaviour, and response.

3.1.3 GET /v1/accounts

Look up accounts by name/phone/email/card/plate. Any combination of filters; returns accounts with balances and status. Results are constrained to the caller's apx_places grant (Part 13 §13.5); under an absent or empty grant the answer is an empty 200 (Part 9 §9.3a).

3.1.4 GET /v1/accounts/{id}

Full account info. Returns the account including balance and status.

3.1.5 GET /v1/payments

Payment history by ticket, card digits, or account. Payments made on a ticket or an account (Part 13 §13.2). At least one key — ticketLast4, cardLast4, ticketNumber, or account — is REQUIRED; date and place only narrow, and a query with no key is 400 invalid-request. Privacy rule: a truncated-key lookup without a date is constrained to the last 8 hours; ticketNumber and account are exempt. Results are constrained to the caller's grant (§13.5). Holds (captureStatus: authorized) are omitted unless captureStatus=authorized is asked for.

3.1.6 POST /v1/payments

Take a payment (idempotent). Takes a payment against an account or ticket. Idempotency-Key REQUIRED. channel: autoAttendant = a PCI-compliant IVR captures the card out of band; APX never carries PANs. Declines are 422. With captureLater: true the payment is authorized only: a hold, created paymentStatus: approved with captureStatus: authorized, returned to this caller but not published or listed by default until captured (Part 13 §13.1a).

3.1.7 POST /v1/payments/{id}/postings

Accounting write-back (PARIS-style). Posts the payment to the monthly-parking/AR system; returns confirmation and new balance. Only an approved payment can be posted; any other state is 409 payment-state-illegal (Part 13 §13.1a).

3.1.8 POST /v1/payments/{id}/refund

Refund a payment (financial domain action). Refunds the payment fully, or partially per amount. A financial action per Part 17 §17.4 — never a control command. Idempotency-Key REQUIRED; approval evidence required when the resolution context's AllowedAction said so. Scope apx.payments:write.

3.1.9 POST /v1/payments/{id}/void

Void a hold (an authorized, uncaptured payment). Financial domain action (Part 17 §17.4). Releases a hold (captureStatus: authorized): paymentStatus becomes reversed, nothing was collected, and no event is published (Part 13 §13.1a). Idempotency-Key REQUIRED. Scope apx.payments:write.

3.1.10 POST /v1/payments/{id}/capture

Capture a hold (a previously authorized payment). Financial domain action (Part 17 §17.4). Settles a hold: captureStatus authorized → captured (paymentStatus stays approved), optionally for a lower amount than was authorized. The capture is when the payment is published and materialized (Part 13 §13.1a). Idempotency-Key REQUIRED. Scope apx.payments:write.

3.1.11 POST /v1/payment-links

Send a hosted payment link. The customer-service payment action of first resort (Part 13 §13.1a): sends a hosted payment link via the given channel for an account, ticket, or session. APX never carries PANs. Idempotency-Key REQUIRED. Scope apx.payments:write. Payment completion arrives as apx.accounts.payment.recorded.v1.

3.1.12 GET /v1/payment-links/{id}

Read a payment link. The link's current lifecycle state (sent → opened → paid | expired | cancelled, Part 13 §13.1a) and, once paid, the resulting PaymentRecord. Grant-checked on the link's place.

3.1.13 POST /v1/payment-links/{id}/cancel

Cancel a payment link. Kills a link before the customer pays (sent to the wrong number, paid another way): sent | opened → cancelled. The hosted page MUST stop accepting payment from that instant. A link that is paid, expired, or already cancelled is 409 payment-state-illegal (Part 13 §13.1a). Idempotency-Key optional (Part 4 §4.2a).

3.1.14 POST /v1/payments/{id}/receipt

Send the receipt again. Re-sends the receipt of a settled payment by e-mail, SMS, a re-print at the device, or a short-lived link (Part 13 §13.1a). The destination travels in the body, never in a URL. Accepted for delivery (202); the outcome is in the returned ReceiptDelivery.

3.2 Reservations

Booking ahead, expressed as conventions over native APDS routes rather than a parallel booking system.

3.2.1 GET /v1/reservations/recent

A customer's last 10 reservations. Customer history for screen-pops and dispute handling: the same holder's most recent reservations (newest planned start first), resolved from a plate or an explicit RightHolder id. At least one of plate or holder is REQUIRED (400 invalid-request otherwise); when both are given the result is their intersection (reservations of that holder carrying that plate). from/to, state, country, and stateProvince narrow further (Part 14 §14.1a).

3.2.2 PUT /v1/sessions/{id}/assigned-right

Link a session to its AssignedRight (reservation/permit). The explicit reservation↔session link for facilities where the plate cannot be the link (barcode-only reservations, unreadable plates). Mirrors plate correction (Part 17 §17.5): a transactional domain action, naturally idempotent (PUT).

3.2.3 POST /v1/sessions/{id}/assigned-right/unlink

Undo a session's link to its AssignedRight. The audited undo of PUT /v1/sessions/{id}/assigned-right (Part 14 §14.1b): removes the linked AssignedRight from the session's current segment, reverts the segment to the implementation's drive-up right, and returns the reservation to its pre-check-in reservationState (confirmed or amended, clearing checkInSession). MUST materialize in the underlying APDS Session and MUST publish SessionUpdated, like the link. reason is REQUIRED. Unlinking a session that carries no linked right is a no-op 200 without unlinkedRight. A closed Session is 422 session-not-open.

3.3 Permits

Pooled permits: issuing from a finite allocation, over the APDS right-specification and right-pool model.

3.3.1 GET /v1/permits/pools/{rightSpecId}/availability

Pool availability for a pooled RightSpecification. Profile over APDS RightPool — capacity, issued, available — for one pool of the RightSpecification. With neither pool nor at, the pool whose validity contains now, else the earliest future pool (Part 14 §14.2).

3.3.2 POST /v1/permits/issue

Issue a permit from a pool (multi-vehicle credentials). Creates a native AssignedRight (APDS annual-permit pattern — one right, many vehicles), materialized per Part 14 §14.2. Pool exhaustion is 409 pool-exhausted. A client that may retry SHOULD send Idempotency-Key: a retried issue without one consumes a second pool slot.

3.4 Validations

The merchant side, from enrolment to invoice.

3.4.1 GET /v1/validations/programs

List/filter validation programs. Filter by place (subtree-inclusive), provider, and status. A apx.validations:redeem token sees only programs whose provider is its own apx_org (Part 20 §20.5).

3.4.2 POST /v1/validations/programs

Enrol a validation program (idempotent). Enrols a merchant to validate parking at a place. Idempotency-Key REQUIRED. The program becomes a row in the Part 6 provider lookup for that place while active. Publishes apx.validations.program.status.v1.

3.4.3 GET /v1/validations/programs/{id}

Read a validation program. Returns the program including rules, billing, and the immutable statusHistory. A redeem token reading another provider's program receives 404, exactly as for a program that does not exist (Part 9 §9.3a rule 2; Part 20 §20.5).

3.4.4 PUT /v1/validations/programs/{id}

Update a validation program (full update, versioned). Full-update semantics (Part 5 §5.1): the body carries the complete program. The precondition is the version last read, sent as If-Match: "<version>" or as the body's version (Part 4 §4.2a); a stale one is 409 version-conflict. Status transitions: active ⇄ suspended, either → ended (terminal; 422 program-not-active for any transition out of ended). Benefit and rule changes apply to redemptions from the update onward; existing instruments keep the benefit they were issued with.

3.4.5 GET /v1/validations/programs/{id}/issuances

List issuances for a program. Batches issued to the program, newest first. Codes are never returned here.

3.4.6 POST /v1/validations/programs/{id}/issuances

Issue a batch of validation instruments (idempotent). Issues quantity instruments of method to the program the path names; the body need not repeat program (a value that differs from the path is 422 request-unprocessable). Idempotency-Key REQUIRED — a retried print job must not double the stock. For code/qrCode/digital, the generated codes[] are returned in THIS response only. Program must be active (422 program-not-active).

3.4.7 GET /v1/validations/instruments/{code}

Check a validation code. "Is this code good?" — the pay-station / merchant-app read before applying. Returns status, program, validity window, and the benefit. A code the caller's grant cannot see is 404, never 403 (no oracle for guessing codes).

3.4.8 POST /v1/validations/programs/{id}/issuances/{issuanceId}/void

Void an issuance batch. Transition issued → void for the batch, and every instrument in it that is valid or expired → void (Part 20 §20.2 rule 5) — the stolen sheet of QR codes. Instruments already redeemed are unaffected; their redemptions stand until reversed. The result's voidDetail.voidedCount says how many codes were voided. A redeem token may void only its own provider's batches (another provider's is 404, §20.5). Voiding a batch already void returns it unchanged (200). No event is published; the instrument read is the source of truth.

3.4.9 POST /v1/validations/instruments/{code}/void

Void a single validation code. Transition one instrument valid or expired → void (Part 20 §20.2 rule 5) — a single leaked code. A redeemed code cannot be voided (422 instrument-invalid; reverse the redemption first). Voiding a code already void returns it unchanged (200). As on the read, a code outside the caller's grant or provider is 404, never 403.

3.4.10 GET /v1/validations/redemptions

List/filter redemptions. Filter by program, place, ticket, session, the Part 6 command that applied it, channel, status, and since (appliedTime). A redeem token sees only its own provider's redemptions (§20.5).

3.4.11 POST /v1/validations/redemptions

Record a redemption (idempotent). Applies a validation to a ticket/session from a pay station, merchant app, or lane device — the data-plane counterpart of the Part 6 applyValidation command (which agents use to act on a lane; it materializes the same resource). Idempotency-Key REQUIRED. The server evaluates the program rules (Part 20 §20.3): 422 program-not-active, request-unprocessable (the body's place is not the program's place or within its subtree), instrument-invalid, redemption-limit-exceeded. On success the session gains the APDS Segment.validationId and amountReduced reflects the ACTUAL reduction. Publishes apx.validations.redeemed.v1.

3.4.12 GET /v1/validations/redemptions/{id}

Read a redemption. Returns the redemption including any reversal and the immutable statusHistory. Another provider's redemption under a redeem token is 404 (Part 9 §9.3a rule 2).

3.4.13 POST /v1/validations/redemptions/{id}/reverse

Reverse a redemption. Transition applied → reversed; the amount due on the session is restored while the session is still open (Part 20 §20.4), and the instrument (if any) returns to valid while still within its window. Already reversed is 409 redemption-reversed. A redemption already billed on a CLOSED statement is reversed too: the closed statement is never edited; reversal.closedStatement names it, and the next statement closed for the program carries a negative credit line (reversal.creditedOn is set when it closes, §20.6).

3.4.14 GET /v1/validations/programs/{id}/statement

Preview a billing statement for a period. Computes the program's redemptions and billable total for from..to under its billing model — a preview (statementStatus: preview, no id), including the credit lines the period would carry. Closing the period is POST …/statements. from not before to is 400 invalid-request.

3.4.15 GET /v1/validations/programs/{id}/statements

List closed statements for a program. Closed statements, newest period first; lines[] omitted.