Record customer acknowledgment of a revised order or invoice
Stamps customer_acknowledged_revision = revision_count on the order, lifting the
revision acknowledgment gate that blocks POST /v1/orders/{id}/payments,
POST /v1/packages (createPackage), and POST /v1/orders/{id}/invoice.
Two call sites:
- Staff API (this endpoint): Entity-scoped API key with
orders:writescope. The operator records the acknowledgment on the customer’s behalf (e.g. after a phone call or in-person confirmation).entity_idis taken from the API key; never from the request body (Layer 1 isolation). - Customer portal (token link):
POST /public/order/{token}/acknowledge-revision(called by the customer from the revision notification email link or the portal page). No API key required; authenticated by the order’sshare_token.
The operation is idempotent — if customer_acknowledged_revision already equals
revision_count, the endpoint returns { already_acknowledged: true } with HTTP 200.
On success, broadcasts order.revision_customer_acknowledged (or
invoice.revision_customer_acknowledged for invoice documents) via the realtime
channel so the operator-side UI immediately re-enables the gated action buttons
without a page refresh.
Activity log: writes an order_revised_customer_acknowledged (or
invoice_revised_customer_acknowledged) audit entry with source: customer_portal
(portal path) or source: staff_api (this endpoint).
Requires: orders:write scope.
Authorizations
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.
Headers
Client-generated unique key for idempotent POST/PATCH/DELETE operations. Alias for the Idempotency parameter. Max 255 chars. On retry with the same key, the original response is returned without re-executing the operation. Keys expire after 24 hours.
255Path Parameters
Body
The body is of type object.
Response
Acknowledgment recorded (or already up-to-date). Returns { acknowledged: true, revision_count: N, customer_acknowledged_revision: N } on first acknowledgment, or { already_acknowledged: true, revision_count: N, customer_acknowledged_revision: N } if the revision was already acknowledged.
True when this call recorded the acknowledgment. Absent (see already_acknowledged) when the revision was already up-to-date.
True when customer_acknowledged_revision already equaled revision_count before this call (idempotent success).
Current value of orders.revision_count.
Value of orders.customer_acknowledged_revision after this call.

