Entity Conditions API

Base URL: https://ecs-api.retailsvc.com/api/v1

Authenticate with an OCMS bearer token (a client_credentials token, or an IAM user token) — your tenant is resolved from it and is never accepted as a request parameter. Each endpoint below lists the permission your token needs.

Before using this reference, read Entity condition, Rules, Project restrictions, and Decisions and outcomes for what these calls actually mean.

---

Entity conditions

List entity conditions

GET /entity-conditions — permission ecs.condition.read

Returns every global entity condition (read-only, platform-owned) plus the conditions your tenant owns. On an id collision, the global condition wins.

[
  {
    "id": "alcohol_se",
    "rule": "AGE_RESTRICTION",
    "scope": "GLOBAL",
    "enabled": true,
    "condition_value": { "minimum_age": 18 }
  }
]

Get an entity condition

GET /entity-conditions/{id} — permission ecs.condition.read

Returns the global condition for the given id if one exists, otherwise your tenant's own. 404 if neither exists.

Create or update a tenant-scoped entity condition

PUT /entity-conditions/{id} — permission ecs.condition.write

Creates or replaces your tenant's condition for {id}. Rejected with 409 if {id} is already used by a global condition — global ids are reserved by the platform.

Request body:

{
  "rule": "AGE_RESTRICTION",
  "enabled": true,
  "condition_value": { "minimum_age": 18 }
}

enabled defaults to true when omitted. rule is one of AGE_RESTRICTION or LICENSE_REQUIREMENT (see Rules); condition_value is { "minimum_age": <int> } for AGE_RESTRICTION, or {} for LICENSE_REQUIREMENT (the license id is the condition's own {id}).

Returns 200 on update or 201 on create, with the resulting condition in the same shape as the list endpoint.

Delete a tenant-scoped entity condition

DELETE /entity-conditions/{id} — permission ecs.condition.delete

Deletes your tenant's condition for {id}. 404 if it doesn't exist; 409 if {id} is a global condition — those can't be deleted through this API.

---

Previewing a decision

Both endpoints below run the same checks a real checkout would, against a single item you supply, without needing a full transaction. Useful for testing a condition or project restriction before relying on it.

Evaluate one entity condition

POST /conditions/{conditionId}/evaluate — permission ecs.condition.evaluate

Resolves {conditionId} from your tenant's catalog, falling back to the global catalog, and evaluates one item against it.

Request:

{
  "item": { "id": "item-1" },
  "context": {
    "customer": { "customer_age": 16 }
  }
}

context.customer is optional — pass {} when there's nothing to supply. See Rules for what each rule reads from it (customer_age for age restriction, licenses for license requirement).

Response (ItemDecisionDto):

{
  "id": "item-1",
  "allow": false,
  "results": [
    {
      "id": "alcohol_se",
      "allow": false,
      "decision": "HARD_DENY",
      "reason": "age_restriction.underage",
      "rule": "AGE_RESTRICTION"
    }
  ]
}

Evaluate project restrictions

POST /project-restrictions/evaluate — permission ecs.condition.evaluate

Looks up the given project's restrictions and evaluates one item against them.

Request:

{
  "projectId": "fc03c9aa-bbb9-413d-997a-be8e9f6f28f0",
  "item": {
    "id": "item-1",
    "additionalProperties": { "department": "hardware", "ecoLabel": false }
  }
}

additionalProperties carries whatever item attributes your project's whitelist/blacklist restrictions check against (see Project restrictions) — omit it entirely if the item has none.

Response is the same ItemDecisionDto shape as above; project-restriction results carry an extra source: "PROJECT_RESTRICTION" and a restriction field naming what was checked (the property name, or "itemId"):

{
  "id": "item-1",
  "allow": false,
  "results": [
    {
      "allow": false,
      "decision": "HARD_DENY",
      "reason": "project_restriction.whitelist_not_met",
      "rule": "PROJECT_RESTRICTION",
      "source": "PROJECT_RESTRICTION",
      "restriction": "department"
    }
  ]
}

---

Response fields reference

ItemDecisionDto:

Field	Type	Notes
id	string	Echoes the item id you sent
allow	boolean	true only if every entry in results allows
results	array	One entry per check that ran, whether it allowed or denied

Each entry in results:

Field	Type	Notes
id	string, optional	Entity condition id, when the result came from one
allow	boolean
decision	ALLOW | SOFT_DENY | HARD_DENY	See Decisions and outcomes
reason	string or null	Machine-readable reason code; null when decision is ALLOW
rule	AGE_RESTRICTION | LICENSE_REQUIREMENT | PROJECT_RESTRICTION
source	string, optional	"PROJECT_RESTRICTION" for project-restriction results
restriction	string or null, optional	Property name or "itemId" for project-restriction results