Sustema

ENTITY developer reference

Fence unstarted work and reconcile in-flight results

Candidate documentation for reading and synthetic examples. Account creation, live API access, SDKs, collections and MCP are not available here. A released service profile and matching integration instructions are required before use.

This is a documentation reading view of an unreleased candidate, not a downloadable replacement schema. Public wire names, types and constraints are retained except for the explicitly marked private-only subsets and route patterns. Private governance references are explained in public language. Use only a separately released, verified generation for clients. Read the explicit exclusions.

POST /v1/classification-orders/{order_id}/cancel

Operation identifier: cancelClassificationOrder

Cancellation linearises in the existing order/acquisition transaction against the owned public order revision. Preserve only acquisitions proved committed for this order before that cut-off; cancel every target not yet committed to it and release its unearned customer reservation. Merely prepared, running, coalesced or privately published worker output earns no customer fee. Fence later attachment/acquisition for the cancelled target. Reconcile genuinely uncertain pre-cut-off owned commits before declaring final money; provider costs alone are Sustema exposure and cannot manufacture a customer financial uncertainty. A late shared result may serve another entitled customer but cannot revive this cancelled target. This binds the cancellation policy: only acquisitions committed before the cancellation cut-off retain their original charge; it does not change tariffs/refunds or cancel another customer's work. Every visible order/operation field, revision, timestamp, count, accounting quantity, reason, error, cursor and notification is derived only from this owner's admitted actions/commitments, proved owned acquisitions/settlements and permitted published evidence. Persist the order public revision, timestamp and visible-content digest separately from private worker revisions. Hidden shared-job progress cannot advance them or make an expected_revision stale. Own accepted actions and changed permitted content atomically advance the public revision; identical replay/read does not. Item-page order_revision and cancellation expected_revision name this same owned revision. Current rights and the whole permitted publication history, including publication times, are part of the projection input. Cancellation of an already terminal completed/completed_partial/unfulfilled/cancelled order returns its unchanged owned terminal projection after current-authority and expected-public-revision checks; it adds no cancellation effect, debit or refund. Stale expected_revision uses stale_revision/412. Nonterminal cancellation retains the existing atomic cutoff/reconciliation rule. For a retired company binding, an ICProblem locator only may use poll_original with status_path /v1/classification-orders/{owned_order_id}, or do_not_retry with no locator. The 202 ICOrder envelope instead uses poll_same_order or do_not_retry and has no status_path field; derive its owned order route from order_id. Never direct recovery to a denied generic operation route. After the owned retained order cutoff, identical createClassificationOrder replay, cancelClassificationOrder and createClassificationAdjustmentRequest return resource_expired/410, do_not_retry, unchanged and null operation/status; never revive a subject-linked body or create a new effect from a tombstone. Expired generic getOperation returns operation_expired/410 with unchanged, do_not_retry and null references, never uncertain/poll-to-self. Underlying uncertain effects continue server-side and survive only in authorised subject-free finance/case status. Legitimate financial claims use existing support-case intake in the signed-in console with original permitted invoice/payment/finance evidence, not expired classification IDs. Current ownership and foreign-resource opacity precede expiry. Original-resource disclosure: The exact original integration service principal, with classification.order.cancel and the exact original revision/cutoff, may cancel its own original order. Release only the original creator’s delegated-human spending bucket for a human-origin order, or original integration’s spending bucket for an integration-origin order, together with its original workspace bucket and original period. A data-access grant is not a counter type. A current steward never becomes the creator or replenishes another bucket. Resolve authentication and exact same-workspace/environment owned relation before action-specific disclosure. Missing/foreign relation is the same opaque resource_not_found404. Only a proved owned relation may return an action-specific permission_denied403. No role or guessed identifier reveals another creator object; an entirely unauthenticated request remains unauthenticated401. Every current credential/action/profile/source/retention guard still applies. Non-retired suspension: A non-retired organisation security/financial suspension admits only the original authenticated integration service principal status/cancellation corridor below. Credential/session/principal revocation, compromised identity or retired binding has its own stricter denial and is never bypassed. Verify the original workspace/environment and integration service-principal identity before route-specific status/reduction. No data read, result/receipt body, new quote/order, funds or entitlement restoration. Token validity alone does not prove original relation. Current organisation suspension denies new work/result routes with existing entitlement_denied403, no reference and unchanged/not_started usage; invalid principal authority uses authority_revoked403. Unknown/foreign originals remain resource_not_found404 before an action-specific denial. Existing getClassificationOrder returns only its owned obligation envelope with items_path=null; cancellation preserves original cut-off and counters. General getOperation/getReceipt remain denied when they would expose result-bearing bodies; recovery uses the existing owned order route, never a new endpoint. This operation policy is original_integration_reduction.

Entity-Service-Profile carries the accepted profile_id; the endpoint pins its separate immutable revision. The retained template parameter description says “revision”; follow this current interpretation when reading that historical wording. No reserved example URL in the definitions is a live service destination.

Authentication

Apply the operation’s security requirement when present, otherwise the contract default below. These definitions do not provision access or qualify an authentication flow.

[
  {
    "bearerAuth": []
  }
]
Security scheme definitions
{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "description": "Validated OAuth access token, never an ID token. Issuer/audience/token endpoint and scope mapping are deployment-profile values. ENTITY current role, data and budget policy additionally applies."
  }
}

Request parameters

Headers, path and query parameters from the candidate contract. Operation-specific definitions take precedence over inherited definitions with the same name and location. Request body fields appear in the reading view below.

Entity-Service-Profile

header · Required

Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation.

Reading definition for Entity-Service-Profile
{
  "name": "Entity-Service-Profile",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string",
    "maxLength": 4096,
    "x-profile-maxLength": "string_characters_max"
  },
  "description": "Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation."
}

order_id

path · Required

Reading definition for order_id
{
  "name": "order_id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "maxLength": 36
  }
}

Idempotency-Key

header · Required

Random UUID for one logical operation, including billed GETs. Same request/key/time replays without a second charge; ENTITY application semantics.

Reading definition for Idempotency-Key
{
  "name": "Idempotency-Key",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "maxLength": 36
  },
  "description": "Random UUID for one logical operation, including billed GETs. Same request/key/time replays without a second charge; ENTITY application semantics."
}

Entity-Operation-Created-At

header · Required

Original creation instant, unchanged on retry. New keys outside the profile admission/skew window are refused even after tombstone expiry.

Reading definition for Entity-Operation-Created-At
{
  "name": "Entity-Operation-Created-At",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string",
    "format": "date-time",
    "maxLength": 35
  },
  "description": "Original creation instant, unchanged on retry. New keys outside the profile admission/skew window are refused even after tombstone expiry."
}

Request and response contract

The candidate operation is shown below with the declared documentation-only public-meaning projection. References open the corresponding public schema. No server URL or credential is supplied by this page.

{
  "operationId": "cancelClassificationOrder",
  "summary": "Fence unstarted work and reconcile in-flight results",
  "description": "Cancellation linearises in the existing order/acquisition transaction against the owned public order revision. Preserve only acquisitions proved committed for this order before that cut-off; cancel every target not yet committed to it and release its unearned customer reservation. Merely prepared, running, coalesced or privately published worker output earns no customer fee. Fence later attachment/acquisition for the cancelled target. Reconcile genuinely uncertain pre-cut-off owned commits before declaring final money; provider costs alone are Sustema exposure and cannot manufacture a customer financial uncertainty. A late shared result may serve another entitled customer but cannot revive this cancelled target. This binds the cancellation policy: only acquisitions committed before the cancellation cut-off retain their original charge; it does not change tariffs/refunds or cancel another customer's work. Every visible order/operation field, revision, timestamp, count, accounting quantity, reason, error, cursor and notification is derived only from this owner's admitted actions/commitments, proved owned acquisitions/settlements and permitted published evidence. Persist the order public revision, timestamp and visible-content digest separately from private worker revisions. Hidden shared-job progress cannot advance them or make an expected_revision stale. Own accepted actions and changed permitted content atomically advance the public revision; identical replay/read does not. Item-page order_revision and cancellation expected_revision name this same owned revision. Current rights and the whole permitted publication history, including publication times, are part of the projection input. Cancellation of an already terminal completed/completed_partial/unfulfilled/cancelled order returns its unchanged owned terminal projection after current-authority and expected-public-revision checks; it adds no cancellation effect, debit or refund. Stale expected_revision uses stale_revision/412. Nonterminal cancellation retains the existing atomic cutoff/reconciliation rule. For a retired company binding, an ICProblem locator only may use poll_original with status_path /v1/classification-orders/{owned_order_id}, or do_not_retry with no locator. The 202 ICOrder envelope instead uses poll_same_order or do_not_retry and has no status_path field; derive its owned order route from order_id. Never direct recovery to a denied generic operation route. After the owned retained order cutoff, identical createClassificationOrder replay, cancelClassificationOrder and createClassificationAdjustmentRequest return resource_expired/410, do_not_retry, unchanged and null operation/status; never revive a subject-linked body or create a new effect from a tombstone. Expired generic getOperation returns operation_expired/410 with unchanged, do_not_retry and null references, never uncertain/poll-to-self. Underlying uncertain effects continue server-side and survive only in authorised subject-free finance/case status. Legitimate financial claims use existing support-case intake in the signed-in console with original permitted invoice/payment/finance evidence, not expired classification IDs. Current ownership and foreign-resource opacity precede expiry. Original-resource disclosure: The exact original integration service principal, with classification.order.cancel and the exact original revision/cutoff, may cancel its own original order. Release only the original creator’s delegated-human spending bucket for a human-origin order, or original integration’s spending bucket for an integration-origin order, together with its original workspace bucket and original period. A data-access grant is not a counter type. A current steward never becomes the creator or replenishes another bucket. Resolve authentication and exact same-workspace/environment owned relation before action-specific disclosure. Missing/foreign relation is the same opaque resource_not_found404. Only a proved owned relation may return an action-specific permission_denied403. No role or guessed identifier reveals another creator object; an entirely unauthenticated request remains unauthenticated401. Every current credential/action/profile/source/retention guard still applies. Non-retired suspension: A non-retired organisation security/financial suspension admits only the original authenticated integration service principal status/cancellation corridor below. Credential/session/principal revocation, compromised identity or retired binding has its own stricter denial and is never bypassed. Verify the original workspace/environment and integration service-principal identity before route-specific status/reduction. No data read, result/receipt body, new quote/order, funds or entitlement restoration. Token validity alone does not prove original relation. Current organisation suspension denies new work/result routes with existing entitlement_denied403, no reference and unchanged/not_started usage; invalid principal authority uses authority_revoked403. Unknown/foreign originals remain resource_not_found404 before an action-specific denial. Existing getClassificationOrder returns only its owned obligation envelope with items_path=null; cancellation preserves original cut-off and counters. General getOperation/getReceipt remain denied when they would expose result-bearing bodies; recovery uses the existing owned order route, never a new endpoint. This operation policy is original_integration_reduction.",
  "tags": [
    "Industry Classification Intelligence"
  ],
  "parameters": [
    {
      "$ref": "#/components/parameters/ServiceProfile"
    },
    {
      "name": "order_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid",
        "maxLength": 36
      }
    },
    {
      "$ref": "#/components/parameters/IdempotencyKey"
    },
    {
      "$ref": "#/components/parameters/OperationCreated"
    }
  ],
  "responses": {
    "202": {
      "description": "Proposed governed response; no deployed endpoint.",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ICOrderResponse"
          },
          "examples": {
            "synthetic_success": {
              "summary": "Synthetic retained original-contract success; not a live service result",
              "value": {
                "data": {
                  "order_id": "11111111-1111-4111-8111-111111111111",
                  "operation_id": "11111111-1111-4111-8111-111111111111",
                  "quote_id": "11111111-1111-4111-8111-111111111111",
                  "quote_digest": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
                  "client_order_reference": "owned-order",
                  "workspace_id": "11111111-1111-4111-8111-111111111111",
                  "environment": "synthetic-review",
                  "revision": 3,
                  "state": "cancelled",
                  "accepted_at": "2026-09-30T09:00:00Z",
                  "updated_at": "2026-09-30T09:01:00Z",
                  "latest_completion_at": "2026-09-30T11:00:00Z",
                  "latest_accounting_at": "2026-09-30T12:00:00Z",
                  "funding_valid_until": "2026-10-01T00:00:00Z",
                  "counts": {
                    "distinct_entities": 1,
                    "requested_standard_results": 1,
                    "pending": 0,
                    "newly_acquired": 0,
                    "already_acquired": 0,
                    "not_qualified": 0,
                    "unavailable": 0,
                    "failed": 0,
                    "cancelled": 1
                  },
                  "accounting": {
                    "unit": "synthetic-credit",
                    "unit_scale": 1,
                    "initial_reserved_units": "1",
                    "outstanding_reserved_units": "0",
                    "gross_debited_units": "0",
                    "released_units": "1",
                    "credited_units": "0",
                    "net_debited_units": "0"
                  },
                  "receipt_ids": [],
                  "items_path": "/v1/classification-orders/11111111-1111-4111-8111-111111111111/items",
                  "cancellation_requested": true,
                  "retry_action": "do_not_retry",
                  "reason_codes": [],
                  "funding_expiry_rule": "duration_eligible_then_earliest_expiry",
                  "offer_binding": {
                    "offer_id": "11111111-1111-4111-8111-111111111111",
                    "offer_version": 1,
                    "offer_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
                    "policy_pins": {
                      "tariff": {
                        "id": "synthetic-policy",
                        "version": "1",
                        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                      },
                      "terms": {
                        "id": "synthetic-policy",
                        "version": "1",
                        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                      },
                      "credit": {
                        "id": "synthetic-policy",
                        "version": "1",
                        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                      },
                      "refresh": {
                        "id": "synthetic-policy",
                        "version": "1",
                        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                      },
                      "retrieval": {
                        "id": "synthetic-policy",
                        "version": "1",
                        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                      },
                      "eligibility": {
                        "id": "synthetic-policy",
                        "version": "1",
                        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                      },
                      "protection": {
                        "id": "synthetic-policy",
                        "version": "1",
                        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                      },
                      "rights": {
                        "id": "synthetic-policy",
                        "version": "1",
                        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                      },
                      "success": {
                        "id": "synthetic-policy",
                        "version": "1",
                        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                      }
                    },
                    "agreement_id": "22222222-2222-4222-8222-222222222222",
                    "agreement_revision": 1,
                    "funded_period_id": "11111111-1111-4111-8111-111111111111",
                    "selection_evidence_id": "22222222-2222-4222-8222-222222222222"
                  },
                  "purpose": "acquisition"
                },
                "meta": {
                  "request_id": "00000007-1111-4111-8111-000000000007",
                  "served_at": "2026-09-07T10:00:00Z",
                  "profile_revision": "synthetic-review-1",
                  "synthetic": true,
                  "replayed": false,
                  "warnings": [
                    "Illustration only; limits, retention and units are not approved production terms."
                  ]
                }
              }
            }
          }
        }
      }
    },
    "410": {
      "description": "Original owned history expired; use existing account case intake for surviving financial claims.",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ICProblem"
              },
              {
                "properties": {
                  "code": {
                    "const": "resource_expired"
                  },
                  "status": {
                    "const": 410
                  },
                  "usage_state": {
                    "const": "unchanged"
                  },
                  "retry_action": {
                    "const": "do_not_retry"
                  },
                  "operation_id": {
                    "type": "null"
                  },
                  "status_path": {
                    "type": "null"
                  }
                }
              }
            ]
          },
          "examples": {
            "owned_resource_expired": {
              "summary": "Synthetic authorised original after its retained resource cutoff; no new effect",
              "value": {
                "type": "https://example.test/problems/resource-expired",
                "title": "Original resource expired",
                "status": 410,
                "code": "resource_expired",
                "request_id": "11111111-1111-4111-8111-111111111111",
                "operation_id": null,
                "usage_state": "unchanged",
                "retry_action": "do_not_retry",
                "status_path": null
              }
            }
          }
        }
      },
      "x-error-codes": [
        "resource_expired"
      ]
    },
    "default": {
      "description": "Typed safe error; inspect original operation after uncertain acceptance.",
      "headers": {
        "Cache-Control": {
          "schema": {
            "const": "private, no-store"
          }
        },
        "Entity-Request-Id": {
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        },
        "Retry-After": {
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": "Provided only when a specific retry delay is known; never implies extra spending authority. Only valid delay-seconds or HTTP-date, no CR/LF; same128-character MCP bound. Unknown timing is omitted, not truncated."
        }
      },
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/ICProblem"
          }
        }
      }
    }
  },
  "x-permission": "classification.order.cancel",
  "x-billable": false,
  "x-commercial-effect": "zero_new_classification_units",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ICCancelRequest"
        }
      }
    }
  },
  "x-cross-adapter-bound": {
    "operation": "cancelClassificationOrder",
    "rule": "#/x-delivery-bound-contract",
    "before_settlement": true
  },
  "x-original-resource-relation": "The exact original integration service principal, with classification.order.cancel and the exact original revision/cutoff, may cancel its own original order. Release only the original creator’s delegated-human spending bucket for a human-origin order, or original integration’s spending bucket for an integration-origin order, together with its original workspace bucket and original period. A data-access grant is not a counter type. A current steward never becomes the creator or replenishes another bucket. Resolve authentication and exact same-workspace/environment owned relation before action-specific disclosure. Missing/foreign relation is the same opaque resource_not_found404. Only a proved owned relation may return an action-specific permission_denied403. No role or guessed identifier reveals another creator object; an entirely unauthenticated request remains unauthenticated401.",
  "x-owned-relation-precedence": "Resolve authentication and exact same-workspace/environment owned relation before action-specific disclosure. Missing/foreign relation is the same opaque resource_not_found404. Only a proved owned relation may return an action-specific permission_denied403. No role or guessed identifier reveals another creator object; an entirely unauthenticated request remains unauthenticated401.",
  "x-non-retired-suspension": {
    "policy": "original_integration_reduction",
    "rule": "A non-retired organisation security/financial suspension admits only the original authenticated integration service principal status/cancellation corridor below. Credential/session/principal revocation, compromised identity or retired binding has its own stricter denial and is never bypassed. Verify the original workspace/environment and integration service-principal identity before route-specific status/reduction. No data read, result/receipt body, new quote/order, funds or entitlement restoration. Token validity alone does not prove original relation. Current organisation suspension denies new work/result routes with existing entitlement_denied403, no reference and unchanged/not_started usage; invalid principal authority uses authority_revoked403. Unknown/foreign originals remain resource_not_found404 before an action-specific denial. Existing getClassificationOrder returns only its owned obligation envelope with items_path=null; cancellation preserves original cut-off and counters. General getOperation/getReceipt remain denied when they would expose result-bearing bodies; recovery uses the existing owned order route, never a new endpoint."
  }
}

Referenced schemas

Includes schemas used by this operation and its shared or inherited parameters. Open a schema to follow its related definitions.

Shared parameter definitions
{
  "Cursor": {
    "name": "cursor",
    "in": "query",
    "required": false,
    "schema": {
      "type": "string",
      "maxLength": 4096,
      "x-profile-maxLength": "string_characters_max"
    },
    "description": "Opaque signed cursor bound to query, organisation, environment, profile, rights and index/publication generation."
  },
  "IdempotencyKey": {
    "name": "Idempotency-Key",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Random UUID for one logical operation, including billed GETs. Same request/key/time replays without a second charge; ENTITY application semantics."
  },
  "Manifest": {
    "name": "manifest_id",
    "in": "query",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Manifest returned by identity/search. A compatibility-bound follow-on read, not unrestricted historical query. Current rights and retention apply."
  },
  "MaxUnits": {
    "name": "Entity-Max-Units",
    "in": "header",
    "required": false,
    "schema": {
      "$ref": "#/components/schemas/Units"
    },
    "description": "Caller ceiling in the accepted offer atomic unit; cannot increase organisation authority."
  },
  "OperationCreated": {
    "name": "Entity-Operation-Created-At",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "date-time",
      "maxLength": 35
    },
    "description": "Original creation instant, unchanged on retry. New keys outside the profile admission/skew window are refused even after tombstone expiry."
  },
  "PageSize": {
    "name": "page_size",
    "in": "query",
    "required": false,
    "schema": {
      "type": "integer",
      "minimum": 1,
      "x-profile-maximum": "page_size_max"
    },
    "description": "Default and maximum from the active profile."
  },
  "ReceiptContext": {
    "name": "Entity-Receipt-Context",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "description": "Readable own-organisation receipt containing the requested entity/manifest. Binds follow-on evidence/module reads to a known permitted result within its retention window; this is not unrestricted historical access."
  },
  "ServiceProfile": {
    "name": "Entity-Service-Profile",
    "in": "header",
    "required": true,
    "schema": {
      "type": "string",
      "maxLength": 4096,
      "x-profile-maxLength": "string_characters_max"
    },
    "description": "Accepted immutable service-profile revision; missing/unknown profiles cannot activate an operation."
  }
}
Inherited path parameters
[]

All API operations