data.commerce.entity.persist

Idempotent upsert into commerce_entity. Restores soft-deleted rows. Keyed by (cloud_connection_uuid, provider, entity_type, external_ref).

Upsert one commerce_entity row by (connection, provider, type, external_ref).

Overview

Property	Value
Workflow type	Atomic
Library	App-commerce
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Org that owns the connection — soft ref, no FK
cloud_connection_uuid	uuid	Yes	—	Connection the entity was fetched through
provider	string	Yes	—	Provider name (bling, conta_azul, tiny, ...)
entity_type	string	Yes	—	product
external_ref	string	Yes	—	Provider-side reference (stringified)
raw	json	Yes	—	Full LTIP contract dump (model_dump(mode='json'))
name	string	No	—	Hot field — entity display name when present
status	string	No	—	Hot field — entity status (active, cancelled, etc.)
provider_updated_at	string	No	—	ISO-8601 — provider's last-modified for incremental sync
last_synced_by_workflow_uuid	string	No	—	workflow UUID of the caller for audit
actor	string	No	—	—

Output Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Org that owns the connection — soft ref, no FK
cloud_connection_uuid	uuid	Yes	—	Connection the entity was fetched through
provider	string	Yes	—	Provider name (bling, conta_azul, tiny, ...)
entity_type	string	Yes	—	product
external_ref	string	Yes	—	Provider-side reference (stringified)
raw	json	Yes	—	Full LTIP contract dump (model_dump(mode='json'))
name	string	No	—	Hot field — entity display name when present
status	string	No	—	Hot field — entity status (active, cancelled, etc.)
provider_updated_at	string	No	—	ISO-8601 — provider's last-modified for incremental sync
last_synced_by_workflow_uuid	string	No	—	workflow UUID of the caller for audit
actor	string	No	—	—
commerce_entity_uuid	uuid	Yes	—	Public UUID of the persisted commerce_entity row
created	boolean	Yes	—	True when a row was inserted; False when updated
restored	boolean	Yes	—	True when a soft-deleted row was reactivated
persisted_at	string	Yes	—	—
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	json	No	—	—
failed_layer	json	No	—	—
error	string	No	—	—
error_type	string	No	—	—
failed_at	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	complete	Upsert commerce_entity row
completed	No	Yes	Yes	—	Upsert succeeded
failed	No	Yes	No	—	Upsert failed

State Diagram

Transitions

From	Action	To	Description
pending	complete	completed	—
pending	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "data.commerce.entity.persist",
  "initial_data": {
    "organization_uuid": "value",
    "cloud_connection_uuid": "value",
    "provider": "value",
    "entity_type": "value"
  }
}