Record Ownership Change

post/extensions/roboledger/{graph_id}/operations/record-ownership-change

Record the parent buying more of a member consolidated in full from its outside owners, or selling some of it to them while keeping control: the share it holds from a month (ownership_pct, staying 50 or more) and the price in cents, with the basis. It sets the member's share from that month and writes a draft in the consolidation entity, dated the month's first day, that its close posts: ASC 810 makes it an equity transaction with no gain or loss. Buying, the price above the book value of the capital bought goes against the investment, the share bought of the member's results since it joined comes out of the outside owners' interest, and the difference is the parent's equity. Selling, the parent's own entry takes the proceeds against the carrying amount of the shares sold and books its gain or loss; the draft reverses that gain, releases the parent's cost above book on those shares, credits the outside owners their larger share of the member's results, and takes the difference to the parent's equity. preview-consolidation-entries then reads the price paid, net of what a sale released, as part of the parent's investment, and the new share from that month. Changes are recorded in order; recording a month again replaces its draft, and a posted one is reversed first. A change across consolidation methods is not supported yet.

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id Constraints: matches `^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?\|sec(?:_[a-zA-Z0-9]{1,20})?\|library)$`

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field	Type	Description
`entity_id`required	string	The member, consolidated in full.
`period`required	string	The month, as YYYY-MM. Constraints: matches `^\d{4}-(0[1-9]\|1[0-2])$`
`ownership_pct`required	number	The parent's share from `period`, as a percentage: above its share the month before for a purchase, below it for a sale, and 50 or more either way, so the member stays consolidated in full. Constraints: at most 100; greater than 0
`consideration`required	integer	Cents the parent paid the outside owners for the shares, or received from them for shares sold. Its line names them, not the member, which is why it is given here. Constraints: at least 0
`basis`required	string	The purchase or sale agreement, or what sets the price. Constraints: at least 1 character

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/record-ownership-change" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "entity_id": "string",
  "period": "string",
  "ownership_pct": 0,
  "consideration": 0,
  "basis": "string"
}'

Responses

200 Successful Response

Field Type Description

operationrequired

string

Kebab-case operation name

operationIdrequired

string

op_-prefixed ULID for audit and SSE correlation

statusrequired

string

Operation lifecycle state

One of: completed, pending, failed

resultoptional

OwnershipChangeResponse

Command-specific result payload

OwnershipChangeResponse fields

Field Type Description

entity_idrequired

string

The member.

entity_namerequired

string

The member's name.

periodrequired

string

The first month the new share holds.

from_pctrequired

number

The parent's share the month before.

to_pctrequired

number

The parent's share from period.

considerationrequired

integer

Cents paid to the outside owners, or received from them for shares sold.

book_valuerequired

integer

Cents: the share bought of the member's capital, which the investment elimination moves from the outside owners to the parent; negative for a share sold, moved the other way.

earnings_transferredrequired

integer

Cents: the share bought of the member's results since it joined, moved from the outside owners' interest to the parent; negative for a share sold.

premium_transferredoptional

integer

Cents: the share bought of the outside owners' interest beyond their share of book value (from the acquisition at fair value, or its step-ups), moved to the parent; negative for a share sold.

Default: 0

carrying_releasedoptional

integer

Cents, for a sale: the carrying amount of the shares sold on the parent's books, its cost pro rata, which its sale entry credits against the investment. Zero for a purchase.

Default: 0

gain_reversedoptional

integer

Cents, for a sale: the gain (a loss negative) the parent's own books take, the price less the carrying amount released, which the entry reverses — the group has none while control is kept. Zero for a purchase.

Default: 0

equity_adjustmentrequired

integer

Cents taken from the parent's equity (negative: added to it): for a purchase, the price above the carrying amount of what was bought; for a sale, the carrying amount given up above the price.

entryrequired

JournalEntryResponse

The ownership change entry, a draft the close posts.

JournalEntryResponse fields

Field	Type	Description
`id`required	string
`transaction_id`optional	string
`type`required	string
`status`required	string
`posting_date`required	string (date)
`memo`optional	string
`provenance`optional	string
`reversal_of`optional	string
`posted_at`optional	string (date-time)
`line_items`required	JournalEntryLineItemResponse[]	One line in a journal entry response.
`total_debit`required	integer
`total_credit`required	integer
`adjustment_kind`optional	string
`adjusts_entity_id`optional	string

replacedoptional

boolean

True when it replaced an earlier draft for the month.

Default: false

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation

idempotentReplayoptional

boolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error