# activities.create ## What it does Register an immutable activity definition. Existing contract terms stay frozen. Discover versions with subjects and documents. Replacement requires the current document ID; replacing with the current definition answers no_change. ## Before you send it An authorized OAuth connection may call it, including a headless client. Effective membership, application grant and token permissions still apply. Describe `activities.create` through `GET /v1/catalog/commands/{name}` before acting. The envelope may reference a registered source document of kind `activity`, `template`, `contract`, `source_document`; this is separate from any evidence required by the input. ## Inputs Put these fields inside the envelope's `input` object. The outer envelope names the command, a stable `idempotency_key` and `effective_at`; [request and recovery rules](/docs/api/) explain those separately. Use exact minor-unit integer strings for monetary fields. Take existing IDs from prior reads or command results; choose a new identity only where the command asks for one. Required means required within its containing object; an optional parent can be omitted. | Field | Type | Required | Meaning and accepted values | |---|---|---|---| | `definition` | object | Yes | | | `definition.model` | string | Yes | Must be `"priced-rights-v1"`. Example: `"priced-rights-v1"`. | | `definition.name` | string | Yes | Minimum length: `1`. Example: `"Consulting access"`. | | `definition.description` | string | No | Minimum length: `1`. | | `definition.externalReferences` | object | No | | | `definition.terms` | object | No | | | `definition.facts` | object | No | | | `definition.ledgers` | object | No | | | `definition.price` | schema-defined | Yes | Choose a matching alternative in the exact schema below. | | `definition.recurringValue` | object | No | | | `definition.recurringValue.interval` | string | Yes | Choose `"monthly"`, `"yearly"`. | | `definition.recurringValue.startTerm` | string | Yes | Minimum length: `1`. | | `definition.recurringValue.endTerm` | string | No | Minimum length: `1`. | | `definition.usage` | object | No | | | `definition.usage.quantityFact` | string | Yes | Minimum length: `1`. | | `definition.usage.schedule` | object | Yes | | | `definition.usage.schedule.startTerm` | string | Yes | Minimum length: `1`. | | `definition.usage.schedule.anchorTerm` | string | No | Minimum length: `1`. | | `definition.usage.schedule.endTerm` | string | No | Minimum length: `1`. | | `definition.usage.schedule.everyMonths` | integer | Yes | Minimum: `1`. Maximum: `120`. | | `definition.usage.schedule.timing` | string | Yes | Choose `"start"`, `"end"`. | | `definition.usage.schedule.offsetDays` | integer | Yes | Minimum: `-365`. Maximum: `365`. | | `definition.usage.schedule.serviceEvidence` | string | No | Must be `"elapsed_time"`. | | `definition.usage.estimate` | string | Yes | Choose `"priced"`, `"observed_amount"`, `"none"`. | | `definition.usage.amountDecimals` | integer | No | Minimum: `0`. Maximum: `9`. | | `definition.usage.allocation` | string | Yes | Choose `"estimate"`, `"quantity"`. | | `definition.usage.customerFunction` | string | No | Choose `"cost_of_revenue"`, `"research_and_development"`, `"sales_and_marketing"`, `"general_and_administrative"`, `"other"`. | | `definition.usage.roundingTolerance` | string | No | Pattern: `"^(term\|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$"`. | | `definition.lot` | object | No | | | `definition.lot.origin` | string | Yes | Choose `"bought"`, `"granted"`. | | `definition.lot.ledger` | string | Yes | Minimum length: `1`. | | `definition.lot.face` | string | Yes | Pattern: `"^(term\|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$"`. | | `definition.lot.expiresAt` | string | No | Pattern: `"^(term\|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$"`. | | `definition.lot.effectiveAt` | string | No | Pattern: `"^(term\|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$"`. | | `definition.lot.coverageBps` | string | No | Pattern: `"^(term\|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$"`. | | `definition.lot.taxPosition` | string | Yes | Choose `"reduces_tax_base"`, `"excludes_tax"`, `"includes_tax"`. | | `definition.lot.refundOnClose` | boolean | Yes | | | `definition.economics` | object | Yes | | | `definition.economics.quantity` | object | No | | | `definition.economics.quantity.term` | string | Yes | Minimum length: `1`. | | `definition.economics.quantity.minimum` | string | No | Pattern: `"^(term\|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$"`. | | `definition.economics.quantity.periodQuantity` | string | Yes | Choose `"at_start"`, `"at_end"`, `"maximum"`, `"time_weighted"`. | | `definition.economics.quantity.proration` | object | Yes | | | `definition.economics.quantity.proration.basis` | string | Yes | Choose `"actual_days"`, `"elapsed"`, `"days_365"`, `"days_30"`, `"true_up_windows"`, `"stated"`, `"none"`. | | `definition.economics.quantity.proration.rounding` | string | Yes | Choose `"half_up"`, `"down"`, `"up"`. | | `definition.economics.quantity.proration.per` | string | Yes | Choose `"change"`, `"unit"`. | | `definition.economics.quantity.increase` | string | Yes | Choose `"now"`, `"next_period"`. | | `definition.economics.quantity.decrease` | schema-defined | Yes | Choose a matching alternative in the exact schema below. | | `definition.economics.quantity.billedOn` | schema-defined | Yes | Choose a matching alternative in the exact schema below. | | `definition.economics.kind` | string | Yes | Choose `"service"`, `"capacity"`, `"ownership"`, `"financing"`, `"distribution"`. Example: `"service"`. | | `definition.economics.direction` | string | Yes | Choose `"provide"`, `"receive"`. Example: `"provide"`. | | `definition.economics.safe` | schema-defined | No | Choose a matching alternative in the exact schema below. | | `definition.economics.billing` | object | No | | | `definition.economics.billing.timing` | string | Yes | Choose `"advance"`, `"arrears"`, `"upfront"`. | | `definition.economics.billing.schedule` | object | No | Choose a matching alternative in the exact schema below. | | `definition.economics.billing.schedule.startTerm` | string | Yes | Minimum length: `1`. | | `definition.economics.billing.schedule.anchorTerm` | string | No | Minimum length: `1`. | | `definition.economics.billing.schedule.endTerm` | string | No | Minimum length: `1`. | | `definition.economics.billing.schedule.everyMonths` | integer | No | Minimum: `1`. Maximum: `120`. | | `definition.economics.billing.schedule.everyDays` | integer | No | Minimum: `1`. Maximum: `366`. | | `definition.economics.billing.schedule.timing` | string | Yes | Choose `"start"`, `"end"`. | | `definition.economics.billing.schedule.offsetDays` | integer | Yes | Minimum: `-365`. Maximum: `365`. | | `definition.economics.billing.schedule.serviceEvidence` | string | No | Must be `"elapsed_time"`. | | `definition.economics.billing.on` | string | No | Choose `"accept"`, `"cancel"`, `"terminate"`. | | `definition.economics.billing.automatic` | boolean | No | | | `definition.economics.billing.dueDays` | integer | No | Minimum: `0`. Maximum: `365`. | | `definition.economics.billing.factsDueDays` | integer | No | Minimum: `1`. Maximum: `90`. | | `definition.economics.billing.factsFrom` | string | No | Pattern: `"^[a-z][a-z0-9_]{0,63}$"`. | | `definition.economics.recognition` | object | No | | | `definition.economics.recognition.timing` | string | Yes | Choose `"delivery"`, `"usage"`, `"ratable"`. | | `definition.economics.recognition.allocation` | string | No | Choose `"equal_periods"`. | | `definition.economics.recognition.schedule` | object | No | Choose a matching alternative in the exact schema below. | | `definition.economics.recognition.schedule.startTerm` | string | Yes | Minimum length: `1`. | | `definition.economics.recognition.schedule.anchorTerm` | string | No | Minimum length: `1`. | | `definition.economics.recognition.schedule.endTerm` | string | No | Minimum length: `1`. | | `definition.economics.recognition.schedule.everyMonths` | integer | No | Minimum: `1`. Maximum: `120`. | | `definition.economics.recognition.schedule.everyDays` | integer | No | Minimum: `1`. Maximum: `366`. | | `definition.economics.recognition.schedule.timing` | string | Yes | Choose `"start"`, `"end"`. | | `definition.economics.recognition.schedule.offsetDays` | integer | Yes | Minimum: `-365`. Maximum: `365`. | | `definition.economics.recognition.schedule.serviceEvidence` | string | No | Must be `"elapsed_time"`. | | `definition.economics.recognition.on` | string | No | Choose `"accept"`, `"cancel"`, `"terminate"`. | | `definition.economics.consideration` | schema-defined | No | Choose a matching alternative in the exact schema below. | | `definition.economics.classification` | object | No | | | `definition.economics.classification.monetaryLedger` | string | Yes | Minimum length: `1`. | | `definition.economics.classification.capitalAccount` | number | No | Choose `3100`, `3110`, `3120`. | | `definition.economics.classification.revenueCategory` | string | No | Choose `"services"`, `"subscription"`, `"consulting"`, `"usage"`, `"grant"`. | | `definition.economics.classification.expenseAccount` | integer | No | | | `definition.economics.classification.expenseFunction` | string | No | Choose `"cost_of_revenue"`, `"research_and_development"`, `"sales_and_marketing"`, `"general_and_administrative"`, `"other"`. | | `definition.economics.classification.product` | string | No | Minimum length: `1`. | | `definition.economics.classification.taxCode` | string | No | Minimum length: `1`. | | `definition.economics.classification.taxTreatment` | string | No | Choose `"inclusive"`, `"exclusive"`. | ## After acceptance When the command emits events, its documented effects and receipt are recorded in the command transaction. The response returns `commandId`, `replayed`, the command-specific `result` below and emitted `events` with their IDs and CIDs. A command is not automatically a cash movement or revenue recognition: use the behavior above to determine what this command records. Inspect `result` and the affected records or reports before continuing. Save returned identifiers for later calls. Fetch `GET /v1/commands/{id}` with `commandId` to recover the accepted receipt; retry the same intent with the same idempotency key if the response was lost. Some commands can succeed with `events: []` and return a transient result and `commandId` without persisting a receipt. A lookup of that ID can return null; retain the returned result and verify the affected record. Retrying can re-evaluate the current state rather than replay a stored result. A domain `no_change` is a separate success outcome with no persisted receipt. ### Result fields Required means required within its containing object; an optional parent can be omitted. | Field | Type | Required | Meaning and accepted values | |---|---|---|---| | `id` | string | Yes | Minimum length: `1`. | | `documentId` | string | Yes | Minimum length: `1`. | | `cid` | string | Yes | Minimum length: `1`. | | `flags` | array | No | Items: string. | [All commands](/docs/command-reference/) · [Operation and errors](/docs/api-reference/operations/commands-execute/) · [Reusable schemas](/docs/api-reference/components/) Keep credentials out of prompts; rehearse writes only in a disposable sandbox. ## Exact request schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "const": "activities.create" }, "input": { "type": "object", "additionalProperties": false, "properties": { "definition": { "type": "object", "additionalProperties": false, "properties": { "model": { "const": "priced-rights-v1" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "externalReferences": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": "string", "minLength": 1 } }, "terms": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "type": { "enum": [ "integer", "text", "date", "instant" ] }, "unit": { "type": "string", "minLength": 1 }, "default": { "type": "string", "minLength": 1 } }, "required": [ "type" ] } }, "facts": { "type": "object", "maxProperties": 100, "additionalProperties": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "enum": [ "integer", "text", "date", "instant" ] }, "unit": { "type": "string", "minLength": 1 } }, "required": [ "type" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "enum": [ "claim", "occurrence" ] } }, "required": [ "type" ] } ] } }, "ledgers": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": "object", "additionalProperties": false, "properties": { "classification": { "enum": [ "gaap", "contractual", "operational", "ownership", "planning" ] }, "unitKind": { "enum": [ "currency", "share", "usage", "credit", "right", "token", "other" ] }, "unitCode": { "type": "string", "minLength": 1 }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18 }, "accountTemplate": { "enum": [ "gaap_startup", "contract_flow", "capacity", "meter", "entitlement", "issued_instrument" ] } }, "required": [ "classification", "unitKind", "unitCode", "decimals", "accountTemplate" ] } }, "price": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "treatment": { "const": "priced" }, "calculation": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "fixed" }, "amount": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" } }, "required": [ "type", "amount" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "capacity_excess" }, "consumptionFact": { "type": "string", "minLength": 1 }, "rate": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "unitsPerPrice": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" } }, "required": [ "type", "consumptionFact", "rate", "unitsPerPrice" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "rate" }, "quantity": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "rate": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "unitsPerPrice": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" } }, "required": [ "type", "quantity", "rate", "unitsPerPrice" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "tiered" }, "quantity": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "mode": { "enum": [ "volume", "graduated" ] }, "tiers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "upTo": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "rate": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "unitsPerPrice": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "flat": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "wholeUnits": { "type": "boolean" }, "startedUnits": { "type": "boolean" } }, "required": [ "rate" ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "type", "quantity", "mode", "tiers" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "sum" }, "components": { "type": "array", "items": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "fixed" }, "amount": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" } }, "required": [ "type", "amount" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "rate" }, "quantity": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "rate": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "unitsPerPrice": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" } }, "required": [ "type", "quantity", "rate", "unitsPerPrice" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "tiered" }, "quantity": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "mode": { "enum": [ "volume", "graduated" ] }, "tiers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "upTo": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "rate": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "unitsPerPrice": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "flat": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "wholeUnits": { "type": "boolean" }, "startedUnits": { "type": "boolean" } }, "required": [ "rate" ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "type", "quantity", "mode", "tiers" ] } ] }, "minItems": 2, "maxItems": 20 } }, "required": [ "type", "components" ] } ] }, "currencyTerm": { "type": "string", "minLength": 1 }, "reductions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string", "minLength": 1 }, "basisPoints": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "amount": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "fromTerm": { "type": "string", "minLength": 1 }, "untilTerm": { "type": "string", "minLength": 1 }, "rounding": { "enum": [ "half_up", "floor" ] }, "appliesTo": { "enum": [ "recurring" ] } }, "required": [ "key", "fromTerm" ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "treatment", "calculation", "currencyTerm" ] }, { "type": "object", "additionalProperties": false, "properties": { "treatment": { "enum": [ "included", "free", "promotional" ] }, "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other" ] }, "ref": { "type": "string", "minLength": 1 }, "signer": { "type": "string", "minLength": 1 } }, "required": [ "kind", "ref" ] }, "minItems": 1, "maxItems": 20 } }, "required": [ "treatment", "evidence" ] }, { "type": "object", "additionalProperties": false, "properties": { "treatment": { "const": "unknown" }, "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "kind": { "enum": [ "tap_message", "x402_receipt", "chain_tx", "signed_doc", "stripe_object", "other" ] }, "ref": { "type": "string", "minLength": 1 }, "signer": { "type": "string", "minLength": 1 } }, "required": [ "kind", "ref" ] }, "minItems": 1, "maxItems": 20 }, "knownAmountTerm": { "type": "string", "minLength": 1 } }, "required": [ "treatment", "evidence" ] } ] }, "recurringValue": { "type": "object", "additionalProperties": false, "properties": { "interval": { "enum": [ "monthly", "yearly" ] }, "startTerm": { "type": "string", "minLength": 1 }, "endTerm": { "type": "string", "minLength": 1 } }, "required": [ "interval", "startTerm" ] }, "usage": { "type": "object", "additionalProperties": false, "properties": { "quantityFact": { "type": "string", "minLength": 1 }, "schedule": { "type": "object", "additionalProperties": false, "properties": { "startTerm": { "type": "string", "minLength": 1 }, "anchorTerm": { "type": "string", "minLength": 1 }, "endTerm": { "type": "string", "minLength": 1 }, "everyMonths": { "type": "integer", "minimum": 1, "maximum": 120 }, "timing": { "enum": [ "start", "end" ] }, "offsetDays": { "type": "integer", "minimum": -365, "maximum": 365 }, "serviceEvidence": { "const": "elapsed_time" } }, "required": [ "startTerm", "everyMonths", "timing", "offsetDays" ] }, "estimate": { "enum": [ "priced", "observed_amount", "none" ] }, "amountDecimals": { "type": "integer", "minimum": 0, "maximum": 9 }, "allocation": { "enum": [ "estimate", "quantity" ] }, "customerFunction": { "enum": [ "cost_of_revenue", "research_and_development", "sales_and_marketing", "general_and_administrative", "other" ] }, "roundingTolerance": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" } }, "required": [ "quantityFact", "schedule", "estimate", "allocation" ] }, "lot": { "type": "object", "additionalProperties": false, "properties": { "origin": { "enum": [ "bought", "granted" ] }, "ledger": { "type": "string", "minLength": 1 }, "face": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "expiresAt": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "effectiveAt": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "coverageBps": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "taxPosition": { "enum": [ "reduces_tax_base", "excludes_tax", "includes_tax" ] }, "refundOnClose": { "type": "boolean" } }, "required": [ "origin", "ledger", "face", "taxPosition", "refundOnClose" ] }, "economics": { "type": "object", "additionalProperties": false, "properties": { "quantity": { "type": "object", "additionalProperties": false, "properties": { "term": { "type": "string", "minLength": 1 }, "minimum": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "periodQuantity": { "enum": [ "at_start", "at_end", "maximum", "time_weighted" ] }, "proration": { "type": "object", "additionalProperties": false, "properties": { "basis": { "enum": [ "actual_days", "elapsed", "days_365", "days_30", "true_up_windows", "stated", "none" ] }, "rounding": { "enum": [ "half_up", "down", "up" ] }, "per": { "enum": [ "change", "unit" ] } }, "required": [ "basis", "rounding", "per" ] }, "increase": { "enum": [ "now", "next_period" ] }, "decrease": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "rule": { "const": "credit_now" }, "credit": { "enum": [ "refund", "vendor_credit" ] } }, "required": [ "rule", "credit" ] }, { "type": "object", "additionalProperties": false, "properties": { "rule": { "enum": [ "no_credit", "next_period", "at_renewal" ] } }, "required": [ "rule" ] }, { "type": "object", "additionalProperties": false, "properties": { "rule": { "const": "within_days" }, "days": { "type": "integer", "minimum": 1, "maximum": 31 }, "credit": { "enum": [ "refund", "vendor_credit" ] } }, "required": [ "rule", "days", "credit" ] } ] }, "billedOn": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "on": { "enum": [ "change", "next_bill" ] } }, "required": [ "on" ] }, { "type": "object", "additionalProperties": false, "properties": { "on": { "const": "true_up" }, "everyMonths": { "type": "integer", "minimum": 1, "maximum": 120 }, "anchor": { "enum": [ "billing", "calendar" ] }, "measure": { "enum": [ "changes", "maximum" ] } }, "required": [ "on", "everyMonths", "anchor", "measure" ] } ] } }, "required": [ "term", "periodQuantity", "proration", "increase", "decrease", "billedOn" ] }, "kind": { "enum": [ "service", "capacity", "ownership", "financing", "distribution" ] }, "direction": { "enum": [ "provide", "receive" ] }, "safe": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "valuationBasis": { "enum": [ "post_money", "pre_money" ] }, "capTerm": { "type": "string", "minLength": 1 }, "discountPpmTerm": { "type": "string", "minLength": 1 } }, "required": [ "valuationBasis", "capTerm" ] }, { "type": "object", "additionalProperties": false, "properties": { "valuationBasis": { "enum": [ "post_money", "pre_money" ] }, "discountPpmTerm": { "type": "string", "minLength": 1 } }, "required": [] } ] }, "billing": { "type": "object", "additionalProperties": false, "properties": { "timing": { "enum": [ "advance", "arrears", "upfront" ] }, "schedule": { "type": "object", "additionalProperties": false, "properties": { "startTerm": { "type": "string", "minLength": 1 }, "anchorTerm": { "type": "string", "minLength": 1 }, "endTerm": { "type": "string", "minLength": 1 }, "everyMonths": { "type": "integer", "minimum": 1, "maximum": 120 }, "everyDays": { "type": "integer", "minimum": 1, "maximum": 366 }, "timing": { "enum": [ "start", "end" ] }, "offsetDays": { "type": "integer", "minimum": -365, "maximum": 365 }, "serviceEvidence": { "const": "elapsed_time" } }, "required": [ "startTerm", "timing", "offsetDays" ], "oneOf": [ { "required": [ "everyMonths" ] }, { "required": [ "everyDays" ] } ] }, "on": { "enum": [ "accept", "cancel", "terminate" ] }, "automatic": { "type": "boolean" }, "dueDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "factsDueDays": { "type": "integer", "minimum": 1, "maximum": 90 }, "factsFrom": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" } }, "required": [ "timing" ] }, "recognition": { "type": "object", "additionalProperties": false, "properties": { "timing": { "enum": [ "delivery", "usage", "ratable" ] }, "allocation": { "enum": [ "equal_periods" ] }, "schedule": { "type": "object", "additionalProperties": false, "properties": { "startTerm": { "type": "string", "minLength": 1 }, "anchorTerm": { "type": "string", "minLength": 1 }, "endTerm": { "type": "string", "minLength": 1 }, "everyMonths": { "type": "integer", "minimum": 1, "maximum": 120 }, "everyDays": { "type": "integer", "minimum": 1, "maximum": 366 }, "timing": { "enum": [ "start", "end" ] }, "offsetDays": { "type": "integer", "minimum": -365, "maximum": 365 }, "serviceEvidence": { "const": "elapsed_time" } }, "required": [ "startTerm", "timing", "offsetDays" ], "oneOf": [ { "required": [ "everyMonths" ] }, { "required": [ "everyDays" ] } ] }, "on": { "enum": [ "accept", "cancel", "terminate" ] } }, "required": [ "timing" ] }, "consideration": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "money" }, "amount": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "currencyTerm": { "type": "string", "minLength": 1 }, "recognition": { "enum": [ "unconditional_obligation", "condition_satisfied" ] } }, "required": [ "type", "amount", "currencyTerm", "recognition" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "units" }, "quantity": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "ledger": { "type": "string", "minLength": 1 } }, "required": [ "type", "quantity", "ledger" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "const": "claim" }, "claimFact": { "type": "string", "minLength": 1 }, "amount": { "type": "string", "pattern": "^(term|fact):[a-zA-Z][a-zA-Z0-9_-]{0,63}$" }, "currencyTerm": { "type": "string", "minLength": 1 } }, "required": [ "type", "claimFact", "amount", "currencyTerm" ] } ] }, "classification": { "type": "object", "additionalProperties": false, "properties": { "monetaryLedger": { "type": "string", "minLength": 1 }, "capitalAccount": { "enum": [ 3100, 3110, 3120 ] }, "revenueCategory": { "enum": [ "services", "subscription", "consulting", "usage", "grant" ] }, "expenseAccount": { "type": "integer" }, "expenseFunction": { "enum": [ "cost_of_revenue", "research_and_development", "sales_and_marketing", "general_and_administrative", "other" ] }, "product": { "type": "string", "minLength": 1 }, "taxCode": { "type": "string", "minLength": 1 }, "taxTreatment": { "enum": [ "inclusive", "exclusive" ] } }, "required": [ "monetaryLedger" ] } }, "required": [ "kind", "direction" ] } }, "required": [ "model", "name", "price", "economics" ] } }, "required": [ "definition" ] }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 256 }, "effective_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "source_document_id": { "description": "A registered document of kind activity, template, contract, source_document that caused this command.", "type": "string", "minLength": 1 } }, "required": [ "name", "input", "idempotency_key", "effective_at" ], "additionalProperties": false } ``` ## Accepted command receipt ```json { "type": "object", "required": [ "commandId", "replayed", "result", "events" ], "properties": { "commandId": { "type": "string" }, "replayed": { "type": "boolean" }, "imported": { "const": true, "description": "The command's events are history from before the business joined Economico, recorded as an import: free of monthly events." }, "result": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "documentId": { "type": "string", "minLength": 1 }, "cid": { "type": "string", "minLength": 1 }, "flags": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "id", "documentId", "cid" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "cid": { "type": "string" } } } } } } ``` ## Example request ```json { "name": "activities.create", "input": { "definition": { "model": "priced-rights-v1", "name": "Consulting access", "price": { "treatment": "free", "evidence": [ { "kind": "other", "ref": "signed-free-access" } ] }, "economics": { "kind": "service", "direction": "provide" } } }, "effective_at": "2026-09-01T00:00:00Z", "idempotency_key": "activities.create-example-0" } ```