API Reference/Escrow

Escrow

Create, advance, and settle escrow transactions between buyers and sellers. Supports milestone-based payouts, negotiated splits, disputes, and admin resolution. All endpoints require x-api-key and x-company-id.

Escrow lifecycle

Initiate

Delivery Note

Goods Received

Release

Query

GET

/v1/escrow

List escrows for the company with optional filters. Supports pagination.

Auth

Field	Type	Required	Description
status	string (query)	No	Filter by escrow status (PENDING, ACTIVE, COMPLETED, CANCELLED, DISPUTED).
buyerId	uuid (query)	No	Filter to escrows where this user is the buyer.
sellerId	uuid (query)	No	Filter to escrows where this user is the seller.
startDate	ISO date (query)	No	Start of the date range.
endDate	ISO date (query)	No	End of the date range.
limit	integer (query)	No	Max number of results to return.
offset	integer (query)	No	Number of results to skip (for paging).

curl -X GET "https://api.switchlock.co.zw/v1/escrow" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Response Example

{
  "data": [
    {
      "id": "esc_01hx...",
      "status": "ACTIVE",
      "totalAmount": "10000",
      "currency": "USD",
      "buyer": { "id": "...", "name": "Tendai M." },
      "seller": { "id": "...", "name": "Farai N." },
      "createdAt": "2026-06-23T10:00:00.000Z"
    }
  ],
  "total": 42
}

GET

/v1/escrow/active

Shortcut to list all currently ACTIVE escrows for the company.

Auth

curl -X GET "https://api.switchlock.co.zw/v1/escrow/active" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Response Example

[{ "id": "esc_01hx...", "status": "ACTIVE", ... }]

GET

/v1/escrow/:id

Retrieve full details for a single escrow, including items, milestones, and split plan.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the escrow.

curl -X GET "https://api.switchlock.co.zw/v1/escrow/value" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Response Example

{
  "id": "esc_01hx...",
  "status": "ACTIVE",
  "externalReference": "INV-001",
  "totalAmount": "10000",
  "currency": "USD",
  "splitPlan": {
    "system_fee_cents": "200",
    "service_fee_cents": "300",
    "seller_payout_cents": "9500"
  },
  "milestones": [],
  "items": [{ "name": "Laptop", "quantity": 1, "pricePerUnit": 10000 }]
}

GET

/v1/escrow/:id/timeline

Retrieve the ordered event timeline for an escrow — every state change, note, and actor recorded.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the escrow.

curl -X GET "https://api.switchlock.co.zw/v1/escrow/value/timeline" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Response Example

[
  { "event": "INITIATED",        "actor": "COMPANY", "at": "2026-06-23T10:00:00.000Z" },
  { "event": "DELIVERY_NOTED",   "actor": "SELLER",  "at": "2026-06-24T09:00:00.000Z" },
  { "event": "GOODS_RECEIVED",   "actor": "BUYER",   "at": "2026-06-25T14:00:00.000Z" },
  { "event": "FUNDS_RELEASED",   "actor": "SYSTEM",  "at": "2026-06-25T14:01:00.000Z" }
]

Initiate

buyerAccountId must belong to the buyer and have sufficient balance. Funds are held (not transferred) until release.

POST

/v1/escrow/initiate

Start a new escrow. Locks funds from the buyer's account and creates escrow records with optional milestones.

Auth

Field	Type	Required	Description
buyerId	uuid	Yes	UUID of the buyer user.
sellerId	uuid	Yes	UUID of the seller user.
buyerAccountId	uuid	Yes	Account to hold funds from.
sellerAccountId	uuid	No	Seller account to receive payout; uses default if omitted.
items	array	Yes	Line items: name, description?, quantity, pricePerUnit.
externalReference	string	Yes	Your unique order reference.
externalInvoiceNumber	string	No	Invoice number for display.
splitPlan	object	No	Custom split: system_fee_cents, service_fee_cents, seller_payout_cents.
feePayer	enum	No	Who pays the fee: BUYER or SELLER.
milestones	array	No	Milestone definitions: title, description?, percentage (0–100). Percentages must sum to 100.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/initiate" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "buyerId": "string",
  "sellerId": "string",
  "buyerAccountId": "string",
  "sellerAccountId": "string",
  "items": [],
  "externalReference": "string",
  "externalInvoiceNumber": "string",
  "splitPlan": {},
  "feePayer": "string",
  "milestones": []
}'

Response Example

{
  "id": "esc_01hx...",
  "status": "ACTIVE",
  "totalAmount": "10000",
  "currency": "USD",
  "createdAt": "2026-06-23T10:00:00.000Z"
}

Delivery & Goods Received

POST

/v1/escrow/:id/delivery-note

Seller records that goods or services have been dispatched. Advances the escrow to DELIVERY_NOTED state.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the escrow.
items	array	Yes	Items delivered: itemId, quantity, price_per_item.
notes	string	No	Optional delivery notes or tracking information.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/delivery-note" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "items": [],
  "notes": "string"
}'

Response Example

{ "status": "DELIVERY_NOTED", "updatedAt": "2026-06-24T09:00:00.000Z" }

POST

/v1/escrow/:id/goods-received

Buyer confirms receipt of goods or services. Advances the escrow to GOODS_RECEIVED.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the escrow.
items	array	Yes	Items received: itemId, quantity, price_per_item.
notes	string	No	Optional receipt notes.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/goods-received" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "items": [],
  "notes": "string"
}'

Response Example

{ "status": "GOODS_RECEIVED", "updatedAt": "2026-06-25T14:00:00.000Z" }

Release

Releasing an escrow is idempotent — send an x-idempotency-key header to safely retry without double-paying.

POST

/v1/escrow/:id/release

Finalize the escrow and transfer funds to the seller per the split plan. For milestone escrows, pass a milestoneId query parameter to release a single milestone.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the escrow.
milestoneId	uuid (query)	No	Release a specific milestone instead of the full amount.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/release" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "milestoneId": "string"
}'

Response Example

{
  "status": "COMPLETED",
  "sellerPayout": "9500",
  "systemFee": "200",
  "serviceFee": "300",
  "transactionId": "txn_..."
}

Negotiations

Either party can propose a revised split plan. The other party must explicitly accept or reject it.

POST

/v1/escrow/:id/negotiate

Propose a new split plan for an escrow.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the escrow.
newSplitPlan	object	Yes	Proposed split: system_fee_cents, service_fee_cents, seller_payout_cents.
actor	enum	Yes	Who is proposing: BUYER or SELLER.
notes	string	No	Reason for the adjustment.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/negotiate" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "newSplitPlan": {},
  "actor": "string",
  "notes": "string"
}'

Response Example

{ "negotiationId": "neg_01hx...", "status": "PENDING" }

POST

/v1/escrow/:id/negotiate/:negId/accept

Accept a pending negotiation proposal.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the escrow.
negId	uuid (path)	Yes	UUID of the negotiation.
actor	enum (body)	Yes	BUYER or SELLER — must be the counterparty who did not propose.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/negotiate/value/accept" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "negId": "string",
  "actor": "string"
}'

Response Example

{ "negotiationId": "neg_01hx...", "status": "ACCEPTED" }

POST

/v1/escrow/:id/negotiate/:negId/reject

Reject a pending negotiation proposal.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the escrow.
negId	uuid (path)	Yes	UUID of the negotiation.
actor	enum (body)	Yes	BUYER or SELLER.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/negotiate/value/reject" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "negId": "string",
  "actor": "string"
}'

Response Example

{ "negotiationId": "neg_01hx...", "status": "REJECTED" }

Milestone Adjustments

For milestone-based escrows, either party can propose a revised payout for a specific milestone before it is released.

POST

/v1/escrow/:id/milestones/:milestoneId/adjust

Propose a revised payout amount for a milestone.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the escrow.
milestoneId	uuid (path)	Yes	UUID of the milestone.
actor	enum (body)	Yes	BUYER or SELLER.
proposedSellerPayoutCents	integer	Yes	New proposed payout in cents.
reason	string	No	Justification for the adjustment.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/milestones/value/adjust" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "milestoneId": "string",
  "actor": "string",
  "proposedSellerPayoutCents": 1000,
  "reason": "string"
}'

Response Example

{ "negotiationId": "neg_01hx...", "status": "PENDING" }

POST

/v1/escrow/:id/milestones/:milestoneId/negotiate/:negId/accept

Accept a milestone adjustment proposal.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	Escrow UUID.
milestoneId	uuid (path)	Yes	Milestone UUID.
negId	uuid (path)	Yes	Negotiation UUID.
actor	enum (body)	Yes	BUYER or SELLER.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/milestones/value/negotiate/value/accept" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "milestoneId": "string",
  "negId": "string",
  "actor": "string"
}'

Response Example

{ "negotiationId": "neg_01hx...", "status": "ACCEPTED" }

POST

/v1/escrow/:id/milestones/:milestoneId/negotiate/:negId/reject

Reject a milestone adjustment proposal.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	Escrow UUID.
milestoneId	uuid (path)	Yes	Milestone UUID.
negId	uuid (path)	Yes	Negotiation UUID.
actor	enum (body)	Yes	BUYER or SELLER.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/milestones/value/negotiate/value/reject" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "milestoneId": "string",
  "negId": "string",
  "actor": "string"
}'

Response Example

{ "negotiationId": "neg_01hx...", "status": "REJECTED" }

Disputes & Cancellation

POST

/v1/escrow/:id/dispute

Raise a formal dispute. The escrow is frozen and escalated for admin review.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the escrow.
actor	enum (body)	Yes	BUYER or SELLER — the party raising the dispute.
reason	string	Yes	Reason for the dispute.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/dispute" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "actor": "string",
  "reason": "string"
}'

Response Example

{ "status": "DISPUTED", "disputeId": "dsp_01hx..." }

POST

/v1/escrow/:id/cancel

Cancel an escrow and return funds to the buyer. Only available before funds are released.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the escrow.
actor	enum	Yes	BUYER, SELLER, or ADMIN.
reason	string	Yes	Reason for cancellation.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/cancel" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "actor": "string",
  "reason": "string"
}'

Response Example

{ "status": "CANCELLED", "refundTransactionId": "txn_..." }

POST

/v1/escrow/:id/admin-resolve

Admin-only: resolve a disputed escrow by imposing a final split plan.

Auth

Field	Type	Required	Description
id	uuid (path)	Yes	UUID of the disputed escrow.
newSplitPlan	object	Yes	Final split: system_fee_cents, service_fee_cents, seller_payout_cents.
adminId	string	Yes	ID of the admin resolving the dispute.

curl -X POST "https://api.switchlock.co.zw/v1/escrow/value/admin-resolve" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "newSplitPlan": {},
  "adminId": "string"
}'

Response Example

{ "status": "RESOLVED", "finalSplit": { ... } }

Next steps

How Escrow Works

Lifecycle diagram and state machine.

Milestone Escrow

Staged payouts tied to deliverable completion.

Disputes & Negotiations

Resolution flow and admin tools.

Payments API

Generate payment links for escrow.