Orders Guide

Complete guide to the order lifecycle - from creation to settlement.

Note

This is the public API/SDK guide for integrators. For internal implementation detail (Orchestrator state machine, signer roles), see docs/guides/orders.md in the repo.

Orders are the core of OFFER-HUB. They represent a transaction between a buyer and seller, with funds protected by escrow until work is completed.

Order Lifecycle

Every order follows a strict state machine — the same canonical diagram used across the docs, matching docs/architecture/state-machines.md in the orchestrator repository exactly:

Mermaid

Rendering diagram…

Note

The escrow contract itself follows a separate internal Escrow state machine while the order machine above advances in parallel.

Creating an Order

Basic Order

bash

curl -X POST http://localhost:4000/api/v1/orders \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440006" \
  -d '{
    "buyerId": "usr_buyer123",
    "sellerId": "usr_seller456",
    "amount": "100.00",
    "currency": "USD",
    "title": "Logo Design",
    "description": "Design a modern logo for my tech startup"
  }'

With SDK

typescript

const order = await sdk.orders.create({
  buyerId: 'usr_buyer123',
  sellerId: 'usr_seller456',
  amount: '100.00',
  currency: 'USD',
  title: 'Logo Design',
  description: 'Design a modern logo for my tech startup'
});

Response

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "ORDER_CREATED",
    "buyerId": "usr_buyer123",
    "sellerId": "usr_seller456",
    "amount": "100.00",
    "currency": "USD",
    "title": "Logo Design",
    "created_at": "2026-02-25T12:00:00.000Z"
  }
}

Order with Milestones

For large projects, create one order with multiple milestones. The milestones belong to the same order and share its escrow; they are not separate orders.

typescript

const order = await sdk.orders.create({
  buyerId: 'usr_buyer123',
  sellerId: 'usr_seller456',
  amount: '5000.00',
  currency: 'USD',
  title: 'Mobile App Development',
  milestones: [
    { ref: 'design', title: 'UI/UX Design', amount: '1000.00' },
    { ref: 'backend', title: 'Backend Development', amount: '2000.00' },
    { ref: 'frontend', title: 'Frontend Development', amount: '1500.00' },
    { ref: 'testing', title: 'Testing & Launch', amount: '500.00' }
  ]
});

Note

Milestone amounts must add up to the total order amount.

Managing Milestones

Milestones are created as part of the parent order. After the order reaches IN_PROGRESS, use the milestone reference to inspect or complete an individual milestone. Completing a milestone updates that milestone within the same order; it does not create a new order or escrow contract.

List Milestones

bash

curl http://localhost:4000/api/v1/orders/ord_xyz789/milestones \
  -H "Authorization: Bearer ohk_live_..."

Response

json

{
  "success": true,
  "data": [
    {
      "id": "mls_abc123",
      "orderId": "ord_xyz789",
      "milestoneRef": "design",
      "title": "UI/UX Design",
      "amount": "1000.00",
      "status": "OPEN",
      "createdAt": "2026-02-25T12:00:00.000Z"
    }
  ]
}

Complete a Milestone

The completion endpoint has no request body. The ref path parameter is the milestoneRef supplied when the order was created.

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/milestones/design/complete \
  -H "Authorization: Bearer ohk_live_..."

Response

json

{
  "success": true,
  "data": {
    "id": "mls_abc123",
    "orderId": "ord_xyz789",
    "milestoneRef": "design",
    "title": "UI/UX Design",
    "amount": "1000.00",
    "status": "COMPLETED",
    "createdAt": "2026-02-25T12:00:00.000Z"
  }
}

Note

A milestone can be completed only while its parent order is IN_PROGRESS. Completing all milestones does not replace the order resolution flow; release the order's funds separately.

Reserving Funds

Before creating escrow, reserve the buyer's funds:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/reserve \
  -H "Authorization: Bearer ohk_live_..."

This moves funds from available to reserved:

Before	After
`available: 100.00`	`available: 0.00`
`reserved: 0.00`	`reserved: 100.00`

Creating and Funding Escrow

Create Escrow Contract

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow \
  -H "Authorization: Bearer ohk_live_..."

This creates a smart contract on Stellar via Trustless Work.

Fund the Escrow

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow/fund \
  -H "Authorization: Bearer ohk_live_..."

This sends USDC from the buyer's invisible wallet to the smart contract on-chain.

Warning

Funding is irreversible until release or refund. The order status becomes ESCROW_FUNDED, then IN_PROGRESS.

Releasing Funds (Happy Path)

When the buyer approves the work:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/release \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"requestedBy": "usr_buyer123"}'

This executes 3 on-chain transactions:

Release from contract to platform
Transfer to seller's wallet
Credit seller's balance

The seller's available balance is credited with the order amount.

Refunding (Without Dispute)

For direct refund from an IN_PROGRESS order:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/refund \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Seller cancelled the order"}'

This refunds 100% to the buyer.

Canceling an Order

From ORDER_CREATED or FUNDS_RESERVED status:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/cancel \
  -H "Authorization: Bearer ohk_live_..."

Note

You cannot cancel after escrow is funded (ESCROW_FUNDED or later).

Handling Disputes

Open a Dispute

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/dispute \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "openedBy": "BUYER",
    "reason": "QUALITY_ISSUE"
  }'

Reasons: NOT_DELIVERED, QUALITY_ISSUE, OTHER

Resolve a Dispute

bash

# Full release to seller
curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"decision": "FULL_RELEASE"}'

# Full refund to buyer
curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"decision": "FULL_REFUND"}'

# Split between both
curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "SPLIT",
    "releaseAmount": "80.00",
    "refundAmount": "20.00",
    "note": "80% of work was completed"
  }'

Listing Orders

bash

# All orders
curl "http://localhost:4000/api/v1/orders" \
  -H "Authorization: Bearer ohk_live_..."

# Filter by status
curl "http://localhost:4000/api/v1/orders?status=IN_PROGRESS" \
  -H "Authorization: Bearer ohk_live_..."

# Filter by buyer
curl "http://localhost:4000/api/v1/orders?buyer_id=usr_buyer123" \
  -H "Authorization: Bearer ohk_live_..."

# Pagination
curl "http://localhost:4000/api/v1/orders?limit=20&cursor=ord_lastid" \
  -H "Authorization: Bearer ohk_live_..."

Events

Subscribe to order events via SSE:

typescript

const events = new EventSource(
  'http://localhost:4000/api/v1/events',
  { headers: { Authorization: 'Bearer ohk_live_...' } }
);

events.onmessage = (e) => {
  const event = JSON.parse(e.data);

  switch (event.eventType) {
    case 'order.created':
      console.log('New order:', event.payload.orderId);
      break;
    case 'order.funds_reserved':
      console.log('Funds reserved for:', event.payload.orderId);
      break;
    case 'order.escrow_funded':
      console.log('Escrow funded:', event.payload.orderId);
      break;
    case 'order.released':
      console.log('Funds released:', event.payload.orderId);
      break;
    case 'order.refunded':
      console.log('Funds refunded:', event.payload.orderId);
      break;
    case 'order.closed':
      console.log('Order closed:', event.payload.orderId);
      break;
  }
};

Best Practices

1. Always Check Balance First

typescript

const balance = await sdk.balance.get(buyerId);
const amount = parseFloat(orderAmount);

if (parseFloat(balance.available) < amount) {
  throw new Error('Insufficient funds');
}

2. Use Idempotency Keys

typescript

const idempotentSdk = sdk.withIdempotencyKey(
  '550e8400-e29b-41d4-a716-446655440007'
);
const order = await idempotentSdk.orders.create({ ... });

3. Handle All States

typescript

switch (order.status) {
  case 'ORDER_CREATED':
    // Show "Waiting for funds" UI
    break;
  case 'FUNDS_RESERVED':
    // Show "Creating escrow" UI
    break;
  case 'IN_PROGRESS':
    // Show "Work in progress" UI
    break;
  case 'DISPUTED':
    // Show "Under review" UI
    break;
  case 'CLOSED':
    // Show "Completed" UI
    break;
}

Next Steps

Escrow Guide - How blockchain escrow works
Disputes Guide - Handling disputes
Events Reference - All order events
API Reference - Full endpoint documentation

Edit this page on GitHub

Orders Guide

Complete guide to the order lifecycle - from creation to settlement.

Note

This is the public API/SDK guide for integrators. For internal implementation detail (Orchestrator state machine, signer roles), see docs/guides/orders.md in the repo.

Orders are the core of OFFER-HUB. They represent a transaction between a buyer and seller, with funds protected by escrow until work is completed.

Order Lifecycle

Every order follows a strict state machine — the same canonical diagram used across the docs, matching docs/architecture/state-machines.md in the orchestrator repository exactly:

Mermaid

Rendering diagram…

Note

The escrow contract itself follows a separate internal Escrow state machine while the order machine above advances in parallel.

Creating an Order

Basic Order

bash

curl -X POST http://localhost:4000/api/v1/orders \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440006" \
  -d '{
    "buyerId": "usr_buyer123",
    "sellerId": "usr_seller456",
    "amount": "100.00",
    "currency": "USD",
    "title": "Logo Design",
    "description": "Design a modern logo for my tech startup"
  }'

With SDK

typescript

const order = await sdk.orders.create({
  buyerId: 'usr_buyer123',
  sellerId: 'usr_seller456',
  amount: '100.00',
  currency: 'USD',
  title: 'Logo Design',
  description: 'Design a modern logo for my tech startup'
});

Response

json

{
  "data": {
    "id": "ord_xyz789",
    "status": "ORDER_CREATED",
    "buyerId": "usr_buyer123",
    "sellerId": "usr_seller456",
    "amount": "100.00",
    "currency": "USD",
    "title": "Logo Design",
    "created_at": "2026-02-25T12:00:00.000Z"
  }
}

Order with Milestones

For large projects, create one order with multiple milestones. The milestones belong to the same order and share its escrow; they are not separate orders.

typescript

const order = await sdk.orders.create({
  buyerId: 'usr_buyer123',
  sellerId: 'usr_seller456',
  amount: '5000.00',
  currency: 'USD',
  title: 'Mobile App Development',
  milestones: [
    { ref: 'design', title: 'UI/UX Design', amount: '1000.00' },
    { ref: 'backend', title: 'Backend Development', amount: '2000.00' },
    { ref: 'frontend', title: 'Frontend Development', amount: '1500.00' },
    { ref: 'testing', title: 'Testing & Launch', amount: '500.00' }
  ]
});

Note

Milestone amounts must add up to the total order amount.

Managing Milestones

List Milestones

bash

curl http://localhost:4000/api/v1/orders/ord_xyz789/milestones \
  -H "Authorization: Bearer ohk_live_..."

Response

json

{
  "success": true,
  "data": [
    {
      "id": "mls_abc123",
      "orderId": "ord_xyz789",
      "milestoneRef": "design",
      "title": "UI/UX Design",
      "amount": "1000.00",
      "status": "OPEN",
      "createdAt": "2026-02-25T12:00:00.000Z"
    }
  ]
}

Complete a Milestone

The completion endpoint has no request body. The ref path parameter is the milestoneRef supplied when the order was created.

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/milestones/design/complete \
  -H "Authorization: Bearer ohk_live_..."

Response

json

{
  "success": true,
  "data": {
    "id": "mls_abc123",
    "orderId": "ord_xyz789",
    "milestoneRef": "design",
    "title": "UI/UX Design",
    "amount": "1000.00",
    "status": "COMPLETED",
    "createdAt": "2026-02-25T12:00:00.000Z"
  }
}

Note

A milestone can be completed only while its parent order is IN_PROGRESS. Completing all milestones does not replace the order resolution flow; release the order's funds separately.

Reserving Funds

Before creating escrow, reserve the buyer's funds:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/reserve \
  -H "Authorization: Bearer ohk_live_..."

This moves funds from available to reserved:

Before	After
`available: 100.00`	`available: 0.00`
`reserved: 0.00`	`reserved: 100.00`

Creating and Funding Escrow

Create Escrow Contract

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow \
  -H "Authorization: Bearer ohk_live_..."

This creates a smart contract on Stellar via Trustless Work.

Fund the Escrow

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/escrow/fund \
  -H "Authorization: Bearer ohk_live_..."

This sends USDC from the buyer's invisible wallet to the smart contract on-chain.

Warning

Funding is irreversible until release or refund. The order status becomes ESCROW_FUNDED, then IN_PROGRESS.

Releasing Funds (Happy Path)

When the buyer approves the work:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/release \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"requestedBy": "usr_buyer123"}'

This executes 3 on-chain transactions:

Release from contract to platform
Transfer to seller's wallet
Credit seller's balance

The seller's available balance is credited with the order amount.

Refunding (Without Dispute)

For direct refund from an IN_PROGRESS order:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/refund \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Seller cancelled the order"}'

This refunds 100% to the buyer.

Canceling an Order

From ORDER_CREATED or FUNDS_RESERVED status:

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/cancel \
  -H "Authorization: Bearer ohk_live_..."

Note

You cannot cancel after escrow is funded (ESCROW_FUNDED or later).

Handling Disputes

Open a Dispute

bash

curl -X POST http://localhost:4000/api/v1/orders/ord_xyz789/resolution/dispute \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "openedBy": "BUYER",
    "reason": "QUALITY_ISSUE"
  }'

Reasons: NOT_DELIVERED, QUALITY_ISSUE, OTHER

Resolve a Dispute

bash

# Full release to seller
curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"decision": "FULL_RELEASE"}'

# Full refund to buyer
curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"decision": "FULL_REFUND"}'

# Split between both
curl -X POST http://localhost:4000/api/v1/disputes/dsp_abc123/resolve \
  -H "Authorization: Bearer ohk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "SPLIT",
    "releaseAmount": "80.00",
    "refundAmount": "20.00",
    "note": "80% of work was completed"
  }'

Listing Orders

bash

# All orders
curl "http://localhost:4000/api/v1/orders" \
  -H "Authorization: Bearer ohk_live_..."

# Filter by status
curl "http://localhost:4000/api/v1/orders?status=IN_PROGRESS" \
  -H "Authorization: Bearer ohk_live_..."

# Filter by buyer
curl "http://localhost:4000/api/v1/orders?buyer_id=usr_buyer123" \
  -H "Authorization: Bearer ohk_live_..."

# Pagination
curl "http://localhost:4000/api/v1/orders?limit=20&cursor=ord_lastid" \
  -H "Authorization: Bearer ohk_live_..."

Events

Subscribe to order events via SSE:

typescript

const events = new EventSource(
  'http://localhost:4000/api/v1/events',
  { headers: { Authorization: 'Bearer ohk_live_...' } }
);

events.onmessage = (e) => {
  const event = JSON.parse(e.data);

  switch (event.eventType) {
    case 'order.created':
      console.log('New order:', event.payload.orderId);
      break;
    case 'order.funds_reserved':
      console.log('Funds reserved for:', event.payload.orderId);
      break;
    case 'order.escrow_funded':
      console.log('Escrow funded:', event.payload.orderId);
      break;
    case 'order.released':
      console.log('Funds released:', event.payload.orderId);
      break;
    case 'order.refunded':
      console.log('Funds refunded:', event.payload.orderId);
      break;
    case 'order.closed':
      console.log('Order closed:', event.payload.orderId);
      break;
  }
};

Best Practices

1. Always Check Balance First

typescript

const balance = await sdk.balance.get(buyerId);
const amount = parseFloat(orderAmount);

if (parseFloat(balance.available) < amount) {
  throw new Error('Insufficient funds');
}

2. Use Idempotency Keys

typescript

const idempotentSdk = sdk.withIdempotencyKey(
  '550e8400-e29b-41d4-a716-446655440007'
);
const order = await idempotentSdk.orders.create({ ... });

3. Handle All States

typescript

switch (order.status) {
  case 'ORDER_CREATED':
    // Show "Waiting for funds" UI
    break;
  case 'FUNDS_RESERVED':
    // Show "Creating escrow" UI
    break;
  case 'IN_PROGRESS':
    // Show "Work in progress" UI
    break;
  case 'DISPUTED':
    // Show "Under review" UI
    break;
  case 'CLOSED':
    // Show "Completed" UI
    break;
}

Next Steps

Escrow Guide - How blockchain escrow works
Disputes Guide - Handling disputes
Events Reference - All order events
API Reference - Full endpoint documentation

Edit this page on GitHub