Skip to main content

NWS Flood Warning — shipments to Southeast, Southwest, West may be affected. Check carrier tracking for delivery updates.

Integrations

Connect Crossflo

Let Crossflo read your FairClose inventory, publish auctions, end lots and learn about sales in real time — with one seller API key and signed webhooks. Nothing here changes how you sign in to FairClose.

Setup in five steps

  1. 1

    Create a Crossflo key

    Seller Dashboard → Integrations → Apps & API → "Set up Crossflo". Choose Read-only for import only, or Read + Write to let Crossflo publish auctions and end lots. Copy the fc_live_… key — it is shown once.

  2. 2

    Paste it into Crossflo

    In Crossflo's FairClose connection settings enter API base https://fairclose.co/api/v1 and the key in the X-API-Key header. Never send the key in a URL or store it in a browser.

  3. 3

    Run the connection check

    Crossflo calls GET /auth/me, /seller/profile and /seller/capabilities to confirm who you are and what the key may do. Compare the seller_id with your dashboard profile.

  4. 4

    Import your inventory

    Crossflo pages through GET /seller/listings?skip=0&limit=100, increasing skip by 100 until has_more is false. Only your own listings are returned.

  5. 5

    Subscribe to webhooks (optional)

    Seller Dashboard → Webhooks → add your Crossflo endpoint for listing.sold, listing.ended_unsold, listing.cancelled and order.shipped so Crossflo can delist, relist or forward tracking without polling.

Quick connection test
curl -H "X-API-Key: fc_live_..." "https://fairclose.co/api/v1/auth/me"
curl -H "X-API-Key: fc_live_..." "https://fairclose.co/api/v1/seller/listings?skip=0&limit=100"
curl -H "X-API-Key: fc_live_..." "https://fairclose.co/api/v1/seller/orders?skip=0&limit=100"

Keys, scopes and safety

One credential per request

Send X-API-Key: fc_live_…. Keys are never treated as browser sessions and no cookie or CSRF token is needed.

Scopes

Read-only: listings, orders, profile. Read + Write: also create drafts, update, publish auctions and end lots. Keys can never create other keys.

Shown once, stored hashed

FairClose keeps only a hash. Lost it? Regenerate — the old key stops working instantly.

Limits

60 requests/minute per key, 5 active keys, optional expiry. Watch X-RateLimit-Remaining.

Formats: send listing_type = auction, fixed_price (eBay Buy It Now / FixedPriceItem) or hybrid (auction + Buy It Now). eBay-style fields buy_it_now_price, price, quantity, custom_label/external_reference (→ SKU) and numeric eBay ConditionIDs are accepted; every listing you read back carries a canonical listing_format.

Status glossary

Every listing Crossflo reads carries one canonical status. FairClose's internal value is echoed as raw_status for debugging only.

statusMeaningWhat Crossflo should do
draftNot live. Created but never published, or scheduled.Keep local stock available
activeLive on FairClose (auction running or Buy It Now available).Hold stock for FairClose
soldConfirmed sale — a winning bid or purchase exists. Check the order payment_status for paid vs awaiting payment.Delist everywhere else
endedEnded without a sale (no bids, reserve not met, or ended early).Safe to relist elsewhere
cancelledWithdrawn by the seller or removed by FairClose.Safe to relist elsewhere
expiredListing duration lapsed without activity.Safe to relist elsewhere

Webhooks & signature verification

Events
HTTPS endpoint, JSON body, signed with your webhook's whsec_… secret. Reply 2xx within 10 s; FairClose retries up to 6 times with backoff.

listing.sold — A lot sold. Includes order_id, sold_price, quantity_sold, payment_status, buyer_id (never buyer e-mail).

listing.ended_unsold — A lot ended without a sale. Includes end_reason, bid_count, relist_allowed: true.

listing.cancelled — A live lot was cancelled or removed. relist_allowed: true.

order.shipped — The seller marked an order shipped. Includes order_id, listing_id, tracking_number, carrier, tracking_url, shipped_at — closes the sale loop.

order.delivered — Carrier tracking (or the buyer/seller) confirmed delivery. Includes delivered_at, confirmed_by, sale_complete: true — mark the sale fully complete.

Headers: X-Webhook-Signature = HMAC-SHA256(secret, raw body) as hex · X-Webhook-Delivery-Id (deduplicate on this) · X-Webhook-Attempt.

Python
import hmac, hashlib, json

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

# FastAPI / Flask example
# raw = await request.body()            # use the RAW bytes, do not re-serialise
# ok  = verify(raw, request.headers["X-Webhook-Signature"], WHSEC)
# event = json.loads(raw)["event"]      # listing.sold | listing.ended_unsold | listing.cancelled
Node.js
import crypto from "node:crypto";

export function verify(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader || ""));
}
// express: app.post("/hooks/fairclose", express.raw({ type: "*/*" }), (req, res) => {
//   if (!verify(req.body, req.get("X-Webhook-Signature"), process.env.FC_WHSEC)) return res.sendStatus(401);
//   res.sendStatus(200); // ack fast, process async; FairClose retries non-2xx up to 6 times
// });

Error codes

Every error body is { "error", "message", "request_id" }. Quote the request_id when you contact support.

401 authentication_requiredNo credential sent
401 invalid_token / expired_tokenBearer JWT problem — refresh or sign in again
401 api_key_invalid / api_key_revoked / api_key_expiredKey unknown, revoked or past its expiry — regenerate in Apps & API
403 insufficient_scopeRead-only key used for a write — issue a Read + Write key
403 ownership_mismatchThe listing belongs to another seller
404 listing_not_foundUnknown listing_id
409 invalid_state / idempotency_conflictAction not valid for the current status, or the Idempotency-Key was reused with a different body
429 rate_limitedOver 60 requests/minute — wait for Retry-After
Back to the Seller Guide