Skip to main content

Creating an order

Alice wants to buy Bob's headphones. Mercatto describes the order's life as a two-state map — waiting for delivery, then delivered — and creates the Transaction that will hold Alice's money, telling Ishtaran up front exactly how it should eventually be split: 90% to Bob, 10% to Mercatto's own commission.

AguardandoEntrega ──(ProdutoEntregue event)──► Entregue

Code​

examples/marketplace-mercatto/create-order.ts
const workflow = await owner.workflows.create(organizationId, 'Mercatto - Ciclo do Pedido');
const version = await owner.workflows.createVersion(
  workflow.workflowId,
  [
    { id: awaitingDeliveryStateId, name: 'AguardandoEntrega', isInitial: true, isFinal: false },
    { id: deliveredStateId, name: 'Entregue', isInitial: false, isFinal: true },
  ],
  [{ id: transitionId, fromStateId: awaitingDeliveryStateId, toStateId: deliveredStateId }],
);
const eventType = await owner.eventTypes.create(organizationId, 'ProdutoEntregue');
await owner.workflows.createRule(workflow.workflowId, version.workflowVersionId, awaitingDeliveryStateId, deliveredStateId, eventType.eventTypeId, []);
await owner.workflows.publishVersion(workflow.workflowId, version.workflowVersionId);

const buyer = { accountId: aliceAccountId, role: 'buyer', isPayer: true };
const seller = { accountId: bobAccountId, role: 'seller', isPayer: false, splitPercentage: '90' };
const marketplace = { accountId: mercattoRevenueAccountId, role: 'marketplace', isPayer: false, splitPercentage: '10' };

const transaction = await mercatto.transactions.create(
  organizationId, applicationId, version.workflowVersionId, assetNetworkId, '200',
  [buyer, seller, marketplace], `mercatto-order-${runId}`,
);

Result​

{ "transactionId": "…", "status": "CREATED" }

What happened under the hood​

Rules must exist before you publish. createRule on an already-Published WorkflowVersion is rejected (422 WORKFLOW_VERSION_NOT_MUTABLE) — real ordering, confirmed live, not a documentation convention.

The Split is explicit on purpose. With two non-payer Participants (Bob and Mercatto), Ishtaran requires an explicit splitPercentage on each — a single beneficiary with no split declared would instead get 100% implicitly (BR-SPL-004, see Failure scenarios for that simpler case). This rule exists because of a real historical financial bug: before it, an implicit-100%-to-one-beneficiary assumption was applied even with two or more beneficiaries, over-crediting whoever happened to be evaluated first. The percentages are validated to sum to exactly 100% at Transaction creation, not at Settlement — an invalid split (say, 90% + 20%) never even produces a Transaction.