Audience: Developers, Support, Ops, Compliance
Outcomes: Working clients; reliable sync; disciplined pre-launch checks; clear escalations
API quick reference
Orders
POST /api/orders GET /api/orders/:orderId GET /api/orders
Deliverables
POST /api/orders/:orderId/deliverables POST /api/orders/:orderId/deliverables/:deliverableId/accept POST /api/orders/:orderId/deliverables/:deliverableId/reject
Escrow
POST /api/escrow/release
Errors
401
login,403
role/KYC,404
wrong ID,400
validationIdempotency: provide a stable reference; server dedupes where possible
Troubleshooting (quick map)
Symptom → Fast fix
Order stuck in DepositPending → Provider webhook not delivered; replay; verify signature; check logs
Upload blocked (type/size) → Convert/compress; check MIME; split archive
Duplicate payout → Ensure unique reference; idempotent release handler
Wrong timezone on due dates → Store UTC; display user locale
Counterparty cannot see deliverable → Share order; verify org context & partner link
Support debug checklist
Confirm user org and role
Capture x-correlation-id, request/response sample, timestamp
Check webhook delivery logs + processed event IDs
Reproduce with minimal
curl
using the same cookie
QA test plan (pre-launch)
Happy paths
Create order with 2 milestones
Upload deliverables; accept/reject → resubmit → accept
Fund deposit via card; webhook ⇒ DepositPaid; set InProgress
Partial then final release; invoice updated
SSE events arrive in browser
Negative paths
Oversized file rejected
Duplicate release blocked by idempotency
Missing KYC blocks release (
403
)Webhook with bad signature rejected (
400
)
Reports
Export orders CSV; totals & counts correct
Evidence bundle contains deliverables + decisions + releases
Operational playbooks
Incident: provider webhook outage
Switch to manual reconciliation: query provider by reference; mark payments in admin back-office with notes
After recovery, replay events; verify no double releases (idempotent handlers)
Incident: large backlog of uploads
Increase worker concurrency; stagger retries; communicate delay via UI banner
Incident: dispute spike
Add pre-acceptance checklist to milestones; enforce reviewer SLAs; analyze common rejection reasons
Escalations
P1: money movement incorrect → on-call engineer + finance lead
P2: delayed reviews/minor webhooks → PM + support