Approve a sales order

Operation ID: approveSalesOrder

Group: Accounting › Sales Orders

Open in the interactive reference

POST /accounting/sales-orders/{id}/approve

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Approves a sales order. Runs the same pre-approval validations the UI gates on and then the full approval cascade — subscription activation, invoice-plan generation, prepaid balances, early-renewal invoicing, draft cleanup, business versioning and metrics. Idempotent: an already-approved order is a no-op success. Does not approve the order's revenue contract. Returns an empty output. Every request must carry the Api-Version header.

POST accounting/sales-orders/3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45/approve

The body is empty and so is the response. Read the order back with GET accounting/sales-orders/{id} to see its approved state.

Until now the only way to approve an order over the api was to send approvalStatus: "approved" when creating it. An order created without that, or one raised in the UI, had no api route to approval at all. This is that route.

Approval is what makes an order real. It runs the same pre-approval validations the UI gates on — milestone configuration, custom invoice plans, VAT estimation, the one-time discount account, subscription status — and then the whole cascade behind them: subscriptions activate, the invoice plan is generated, prepaid balances are created, early renewals are invoiced, superseded draft modifications are cleaned up, business-version logs and metrics are written. An order refused by a validation rule is left entirely untouched; the call runs in a transaction, so a failure part-way leaves nothing behind.

Approving is idempotent. An order that is already approved returns success and changes nothing — the cascade is deliberately not re-run, since it creates prepaid balances and deletes drafts. The SALES_ORDER_ALREADY_APPROVED information diagnostic is how a caller tells that case from a fresh approval (SALES_ORDER_APPROVED), so a retry after a timeout is safe.

It does NOT approve the order's revenue contract. That is a separate, explicit call: POST accounting/revenue-contracts/{id}/approve. The order must be approved first — the contract's own route refuses it otherwise.

Approving an id that does not exist is NOT_FOUND, not a silent success.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.
id path string yes Id (a UUID) of the sales order to approve; bound from the :id path segment. Example: "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45".

Response

200 Success

{
  "data": {},
  "diagnostics": [
    {
      "code": "SALES_ORDER_APPROVED",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    }
  ]
}

Response headers

Errors

Code Status
NOT_FOUND 400
VALIDATION_FAILED 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Advisories

Warnings and information a successful response can carry under diagnostics:

Statuses