Skip to main content

Initiate Settlement

POST 
/v1alpha1/issuers/:issuerId/secondaryTransactions

Scope(s): readwrite_issuer_secondarytransactions

Creates a secondary transaction, soft-locks each security being settled, and returns the transaction identifier. Persist the returned secondaryTransactionId — every later call is addressed by it.

The soft lock stops a holder placing a cash exercise against the same vested options inside Carta while your settlement is in flight. Carta takes it itself; there is no lock call for you to make and no lock resource on this API. It is released automatically when the transaction reaches a terminal state.

The transfer versus repurchase distinction is carried by rightOfFirstRefusalOutcome rather than by separate endpoints: EXERCISED_BY_COMPANY drives the repurchase path, and the other two drive the transfer path. buyerInformation is required on the transfer path and unused for a repurchase, where the issuer is the counterparty.

Branch on transactionState in the response, not on the status code. PENDING_SETTLEMENT means the settlement contains certificates only — you may move money and call Finalize Settlement. PENDING_ISSUER_OPTION_COST_REVIEW means it contains at least one option grant, and the issuer must approve the option cost and withholding before the tax figures are released to you; wait for the withholding notification, then read the transaction to obtain them.

The cap table is not touched here. That happens after Finalize Settlement, once the issuer approves the cap-table update.

Request​

Responses​

A successful response.