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
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
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
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
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
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.
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.
| status | Meaning | What Crossflo should do |
|---|---|---|
| draft | Not live. Created but never published, or scheduled. | Keep local stock available |
| active | Live on FairClose (auction running or Buy It Now available). | Hold stock for FairClose |
| sold | Confirmed sale — a winning bid or purchase exists. Check the order payment_status for paid vs awaiting payment. | Delist everywhere else |
| ended | Ended without a sale (no bids, reserve not met, or ended early). | Safe to relist elsewhere |
| cancelled | Withdrawn by the seller or removed by FairClose. | Safe to relist elsewhere |
| expired | Listing duration lapsed without activity. | Safe to relist elsewhere |
Webhooks & signature verification
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.
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.cancelledimport 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_required | No credential sent |
| 401 invalid_token / expired_token | Bearer JWT problem — refresh or sign in again |
| 401 api_key_invalid / api_key_revoked / api_key_expired | Key unknown, revoked or past its expiry — regenerate in Apps & API |
| 403 insufficient_scope | Read-only key used for a write — issue a Read + Write key |
| 403 ownership_mismatch | The listing belongs to another seller |
| 404 listing_not_found | Unknown listing_id |
| 409 invalid_state / idempotency_conflict | Action not valid for the current status, or the Idempotency-Key was reused with a different body |
| 429 rate_limited | Over 60 requests/minute — wait for Retry-After |