Escrow / Holds - API Docs

Escrow / Credit Holds

Reserve credits from a user's balance into escrow, then either release them back to the holder or capture (settle) them — optionally crediting a different end user for peer-to-peer and marketplace flows. The lifecycle is hold → release | capture; a partial capture automatically releases the uncaptured remainder back to the holder.

Create a Hold

Move credits out of a user's spendable balance and into a held state. Held credits no longer count toward their balance until released or captured.

// Reserve credits into escrow (hold)
const response = await fetch(
  'https://eutdgemlrpvnxfkkpvlu.supabase.co/functions/v1/credits-api/escrow/hold',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'sk_live_your_api_key'
    },
    body: JSON.stringify({
      user_email: 'buyer@example.com',
      credit_type_id: 'ct_abc123',
      amount: 100,
      reference_id: 'order_789'
    })
  }
);

const result = await response.json();
// { success: true, hold_id: 'hold_abc123', status: 'held', amount: 100, new_balance: 150 }

Capture or Release

Capture settles the hold — optionally to a different user. Release cancels the hold and returns the full amount to the original holder.

// Capture (settle) a hold — optionally to a different user (marketplace/P2P).
// Any uncaptured remainder is released back to the holder.
const response = await fetch(
  'https://eutdgemlrpvnxfkkpvlu.supabase.co/functions/v1/credits-api/escrow/capture',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'sk_live_your_api_key'
    },
    body: JSON.stringify({
      hold_id: 'hold_abc123',
      to_user_email: 'seller@example.com'
      // amount: 60  // optional — partial capture, remainder released
    })
  }
);

const result = await response.json();
// {
//   success: true,
//   hold_id: 'hold_abc123',
//   status: 'captured',
//   captured_amount: 100,
//   remainder_released: 0,
//   to_user_id: 'seller_456',
//   recipient_new_balance: 100,
//   holder_new_balance: 150
// }
// To cancel instead, POST /escrow/release with { hold_id }.

Escrow API Endpoints

Endpoint	Description
POST /escrow/hold	Reserve credits into escrow
POST /escrow/release	Cancel a hold, returning credits to the holder
POST /escrow/capture	Settle a hold, optionally to another user
GET /escrow	List holds (filter by status, reference_id, user)

Marketplace Settlement Flow

Buyer places an order — hold their credits with POST /escrow/hold
Order is fulfilled — capture to the seller with POST /escrow/capture
Order is cancelled — release back to the buyer with POST /escrow/release
Partial fulfillment — capture part; the remainder is auto-released

Your first credit is one request away.

Create a project, copy an API key, and issue a credit from your server.

Get an API key Open the dashboard