EconomicoGET /v1/subjects/{type}
Read derived lifecycle state. Call types first: it lists every subject type with its statuses and the filters its list accepts. List and get require type; get requires id. List supports status, the type’s declared filters (email, code, contract_id, activity_key, document_id, record_type, plan, kind, party_id, activity_document_id, template_document_id), ids (1–500 subject ids of the type, those it holds in id order) and an exclusive subject-ID after cursor; a filter the type does not declare is refused. The contract kind filter accepts customer, vendor, investment or other, derived from its saved roles and rights; it returns busy while bounded historical index catch-up is pending, and requires schema 27. On contracts, party_id lists those naming a party in any role, activity_document_id those binding a right’s document version and template_document_id those made from a template or plan document version; each of these two also takes a list of 1–500 versions and matches a contract on any of them, with no other filter; otherwise filters combine. Activity and template rows carry versions, every document the record has been, oldest first. An activity_occurrence’s state carries recordType (invoice, payment_receipt, bill, bill_payment, refund, credit_note, cancellation or activity_statement), and record_type filters by it. Types carry a founder label and note; activity, template, contract and activity_occurrence rows carry label and title (an occurrence also counterpartyId and, when its headline effect is money, amount, currency and decimals). An invoice, bill or receipt is titled by its occurrence key; a recording that moved nothing (an acceptance, a delivery) by the name of the activity it ran; correlate on state.occurrenceKey, never on title.
All operations · Reusable schemas
Complete operation contract
{
"operationId": "subjects.list",
"description": "Read derived lifecycle state. Call types first: it lists every subject type with its statuses and the filters its list accepts. List and get require type; get requires id. List supports status, the type's declared filters (email, code, contract_id, activity_key, document_id, record_type, plan, kind, party_id, activity_document_id, template_document_id), ids (1–500 subject ids of the type, those it holds in id order) and an exclusive subject-ID after cursor; a filter the type does not declare is refused. The contract kind filter accepts customer, vendor, investment or other, derived from its saved roles and rights; it returns busy while bounded historical index catch-up is pending, and requires schema 27. On contracts, party_id lists those naming a party in any role, activity_document_id those binding a right's document version and template_document_id those made from a template or plan document version; each of these two also takes a list of 1–500 versions and matches a contract on any of them, with no other filter; otherwise filters combine. Activity and template rows carry versions, every document the record has been, oldest first. An activity_occurrence's state carries recordType (invoice, payment_receipt, bill, bill_payment, refund, credit_note, cancellation or activity_statement), and record_type filters by it. Types carry a founder label and note; activity, template, contract and activity_occurrence rows carry label and title (an occurrence also counterpartyId and, when its headline effect is money, amount, currency and decimals). An invoice, bill or receipt is titled by its occurrence key; a recording that moved nothing (an acceptance, a delivery) by the name of the activity it ran; correlate on state.occurrenceKey, never on title.",
"parameters": [
{
"name": "X-Economico-Business",
"in": "header",
"required": true,
"description": "Explicit business slug for this request; must be approved by the connection and token.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"default": 100
}
},
{
"name": "type",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "effective_at",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "ids",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"minItems": 1,
"maxItems": 500
}
},
{
"name": "email",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "contract_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "activity_key",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "document_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "record_type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "plan",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "kind",
"in": "query",
"required": false,
"schema": {
"enum": [
"customer",
"vendor",
"investment",
"other"
]
}
},
{
"name": "party_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "activity_document_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"minItems": 1,
"maxItems": 500
}
],
"description": "One document version, or a list of 1–500 to match a contract on any of them."
}
},
{
"name": "template_document_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"minItems": 1,
"maxItems": 500
}
],
"description": "One document version, or a list of 1–500 to match a contract on any of them."
}
}
],
"responses": {
"200": {
"description": "Canonical result; missing read objects are null. Money is in decimal integer strings.",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Invalid envelope, query or domain input; also `missing_rates`, a foreign-currency command whose exchange rates the shared store could not supply (`details.missing_rates: [{ base, quote, date }]`, plus `details.refusal: { code, message }` when the command also refused), answered by stating an evidenced `exchangeRate`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token. Follow the WWW-Authenticate resource_metadata URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"WWW-Authenticate": {
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "plan_required: the command needs a platform plan this business is not on (members beyond the owner and shared views need Founders or Startup), or the command would record more events than Solo's monthly allowance has left. The allowance refusal writes nothing (a retry may keep its idempotency key) and carries `details: { reason, included, used, requested, from, through }` (counts as decimal strings; `from`/`through` the current events period as UTC instants). `reason` `solo_limit`: Solo's allowance; tell the founder the limit and that it resets at `through`, then retry after `through`, or once they accept paid extra events or upgrade to a paid plan `details.choices` names (`founders` while the team fits Founders, `team` for Startup; each with its own offer for `platform_purchase`). `reason` `plan_cancelled`: Startup was cancelled, or Solo's extra events were turned off; the extra events so far were billed then, and until the plan ends at `endsAt` the business has only `allowed` events in each billing period (its included events, or up to the end of a started block the cancellation billed), with no further extra events; after that it is on Solo (`after` `solo`, for Startup); retry after `through` (the next period's included events) or after `endsAt`. Tell the founder; they can keep Startup (or the extra events) from the billing page once the extra events billed then are paid (for monthly Startup whose cancellation billed extra events, keeping it takes a new Startup agreement from the end; a first-year YC price cannot carry over, so that plan ends as scheduled), or choose it again once it has ended. Any new paid plan (Startup, extra events, a switch or that new agreement) starts only once every invoice from Economico is paid; until then the billing page says so. `reason` `usage_settled`: Startup or Solo's extra events were kept after a cancel; this period's usage was settled then, so retry after `through`. With `details.closesAt`, the business is set to close then (its owner approved closing it): tell the founder, and do not wait for `endsAt` or suggest keeping or upgrading the plan; the owner can stop the closing at /account/cancel until then. Reads, exports and payment setup stay available, and so does upgrading unless the business is set to close (`closesAt`).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Membership revoked, business unavailable for writes, or command credential requirements not met (browser-only commands refuse all OAuth tokens). `demo_business`: the business is a demo (`demo: true` on the business read: fictional, its owner's alone) and the command would reach someone else, send a message (support included, for now), publish it, take a plan or make it look like a real company, or the demo has recorded the 2,000 events it may record; tell the user, who can create their own business to do this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Unknown route or missing required resource.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"405": {
"description": "Method not supported.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Allow": {
"schema": {
"type": "string"
}
}
}
},
"408": {
"description": "Request body transfer timed out (code `upload_timeout`): it took over 30 s, or paused over 5 s between chunks; retry the same request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Domain or idempotency conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"411": {
"description": "Length required (code `length_required`): a JSON body larger than 256 KiB must send Content-Length.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "Payload too large (code `payload_too_large`): the request body exceeds the admitted byte limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "JSON body required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Address rate budget exhausted. Wait for Retry-After seconds before retrying.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string",
"pattern": "^[0-9]+$"
}
}
}
},
"500": {
"description": "Internal failure.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Busy (code `busy`): the business is still receiving other document uploads or serving other large documents, and did not start this request. Retry the same request after Retry-After seconds.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "string"
}
}
}
}
}
}