Operation payload | 21yield Developers

What It Does

Use category: "operation" to attach business operation data to a disbursement. This can include revenue, cost, operating dates, and optional asset fields.

Field Summary

Required Fields

Field	Required	Notes
`operation_id`	Always	Unique operation identifier.
`step`	Always	`create`, `update`, or `delete`.
`disbursement_id`	Create	Parent disbursement id.
`operation_name`	Create	Short operation name.

Common optional fields:

An operation can be a trade finance operation, an asset-backed operation or any given type of operation.

Use the optional fields that best describe your usecase.

Field	Notes
`operation_description`	Longer description of the operation.
`operation_start_date`	Operation start date. Accepts ISO 8601 date-only or timestamp input.
`operation_end_date`	Operation end date. Accepts ISO 8601 date-only or timestamp input.
`operation_revenue`	Numeric operation revenue.
`operation_cost`	Numeric operation cost.
`currency`	ISO 4217 code. Keep aligned with related amounts.
`asset_id`	Asset identifier when operation has asset context.
`asset_type`	Asset type when operation has asset context.
`asset_value`	Asset value when operation has asset context.
`asset_description`	Asset description when operation has asset context.
`asset_purchase_date`	Asset purchase date. Accepts ISO 8601 date-only or timestamp input.
`asset_condition`	Current asset condition. Sending a non-empty value creates a worker-managed asset status row.
`depreciation_amount`	Depreciation amount. Requires `asset_id` or `asset_value`.
`depreciation_period`	Depreciation period: `daily`, `monthly`, `quarterly`, or `yearly`. Requires `asset_id` or `asset_value`.
`depreciation_method`	Depreciation method: `straight_line` or `amortization`. Requires `asset_id` or `asset_value`.
`info`	Additional structured metadata.

Allowed depreciation_period: daily, monthly, quarterly, yearly. Allowed depreciation_method: straight_line, amortization.

Create Operation

{
  "category": "operation",
  "data": {
    "step": "create",
    "operation_id": "OP-2024-001",
    "disbursement_id": "DSB-2024-001",
    "operation_name": "Vehicle lease activity",
    "operation_description": "Revenue operation backed by a vehicle asset",
    "operation_start_date": "2024-10-20T12:34:56Z",
    "operation_revenue": 1000,
    "operation_cost": 250,
    "currency": "USD",
    "asset_id": "AST-2024-001",
    "asset_type": "vehicle",
    "asset_value": 15000,
    "asset_condition": "active",
    "depreciation_amount": 100,
    "depreciation_period": "monthly",
    "depreciation_method": "straight_line"
  }
}

Update

Use step: "update" with the same operation_id and fields to change.

{
  "category": "operation",
  "data": {
    "step": "update",
    "operation_id": "OP-2024-001",
    "operation_revenue": 1250,
    "operation_cost": 275
  }
}

Delete

{
  "category": "operation",
  "data": {
    "step": "delete",
    "operation_id": "OP-2024-001"
  }
}

Notes

Use operation for asset-related source fields.
Depreciation fields need either asset_id or asset_value.
Sending non-empty asset_condition creates a worker-managed asset status row. asset_purchase_date is used as the status date when present.
Updates require operation_id; include disbursement_id only when changing or clarifying parent linkage.
Operation/asset/depreciation monetary fields use API-owned cent rounding. Extra decimals are accepted; numeric strings and unknown fields are not.
Duplicate creates return 409; missing updates return 404. Parent disbursements must exist.
Hash-matching updates return 200 unchanged and do not generate asset-status rows or refresh domain timestamps. Preserve original content/key when retrying.