Skip to content

Crossflo API documentation

Base URL https://crossflo.io/api/v1. All responses are JSON over HTTPS. Times are ISO 8601 in UTC; money is a decimal number with a currency code.

Quick start

  1. Register an app and save your client ID and secret.
  2. Send the seller to the authorize URL with PKCE (below) and the permissions you need.
  3. Exchange the returned code for tokens at the token endpoint.
  4. Call GET https://crossflo.io/api/v1/me with Authorization: Bearer ACCESS_TOKEN.

Apps and review

Personal apps work instantly at Starter limits, but only for your own Crossflo account — ideal for scripts and tools for your shop. Commercial apps can be connected by any Crossflo seller after Crossflo reviews them (usually a few business days). Request only the permissions you need; you can ask for more later. Rejected or suspended apps stop working immediately.

Sign in with Crossflo (OAuth 2.1 + OpenID Connect)

Crossflo uses the authorization code flow with PKCE (S256). Discovery document: https://jrhlclhfviypvmeonpvt.supabase.co/auth/v1/.well-known/openid-configuration.

Issuerhttps://jrhlclhfviypvmeonpvt.supabase.co/auth/v1
Authorizehttps://jrhlclhfviypvmeonpvt.supabase.co/auth/v1/oauth/authorize
Tokenhttps://jrhlclhfviypvmeonpvt.supabase.co/auth/v1/oauth/token
User infohttps://jrhlclhfviypvmeonpvt.supabase.co/auth/v1/oauth/userinfo
JWKShttps://jrhlclhfviypvmeonpvt.supabase.co/auth/v1/.well-known/jwks.json
Supported scopesopenid email profile phone offline_access
Client authenticationclient_secret_basic (server apps)
1. Send the seller to Crossflo
https://jrhlclhfviypvmeonpvt.supabase.co/auth/v1/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback
  &scope=openid%20email%20profile%20offline_access
  &state=RANDOM_STATE
  &code_challenge=BASE64URL(SHA256(CODE_VERIFIER))
  &code_challenge_method=S256

The seller signs in to Crossflo (email, Google, or another sign-in they use), sees your app's name and permissions, and chooses Allow or Deny. You get ?code=…&state=… on your redirect URI — check that state matches.

2. Exchange the code (server side)
curl -X POST https://jrhlclhfviypvmeonpvt.supabase.co/auth/v1/oauth/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=CODE \
  -d redirect_uri=https://yourapp.com/callback \
  -d code_verifier=CODE_VERIFIER

{ "access_token": "eyJ…", "token_type": "bearer", "expires_in": 3600,
  "refresh_token": "…", "id_token": "eyJ…", "scope": "openid email profile offline_access" }

Add a “Sign in with Crossflo” button

Use the Crossflo blue and the words “Sign in with Crossflo” or “Continue with Crossflo”. Link it to your server route that starts the flow above.

HTML
<a href="/auth/crossflo/start"
   style="display:inline-flex;align-items:center;gap:8px;padding:10px 16px;border-radius:8px;
          background:#1d4ed8;color:#fff;font:600 14px system-ui;text-decoration:none">
  Continue with Crossflo
</a>

The ID token (or GET https://jrhlclhfviypvmeonpvt.supabase.co/auth/v1/oauth/userinfo) gives the seller's Crossflo ID (sub), email and whether it's verified. Use sub as the stable key for the account, not the email.

Tokens and refresh

Access tokens last about an hour. Live Crossflo discovery supports offline_access; our example requests it. Register both authorization_code and refresh_token grants, and refresh before calling again. Registered profile permission covers identity scopes, not listing or order access; phone sharing is not currently available to developer apps. Keep refresh tokens and your client secret on your server only. If a seller disconnects your app, refresh fails and API calls return 401 — ask them to connect again.

Refresh
curl -X POST https://jrhlclhfviypvmeonpvt.supabase.co/auth/v1/oauth/token -u "CLIENT_ID:CLIENT_SECRET" \
  -d grant_type=refresh_token -d refresh_token=REFRESH_TOKEN

Permissions

Permissions are set on your app (and reviewed for commercial apps). Sellers see them on the Allow screen.

  • profile — Basic profile

    Name, email and Crossflo account ID (Sign in with Crossflo).

  • intake.write — Purchase intake

    Create draft items with recorded purchase facts; Pro+ owner key required.

  • items.read — Read items

    Items, prices, costs, photos and where each is listed.

  • orders.read — Read orders

    Sales, sale prices, fees and buyer names.

GET /me

The seller who authorized your app. Needs profile.

GET https://crossflo.io/api/v1/me

{ "id": "3b1f…", "email": "seller@example.com", "email_verified": true, "name": "Pat Seller",
  "app_plan": "starter", "permissions": ["profile", "items.read"] }

GET /items

The seller's items, most recently changed first. Needs items.read. Query: limit (default 50, up to your plan's page size), cursor, status (e.g. active, draft, sold), updated_since (ISO time — use it to sync only what changed).

GET https://crossflo.io/api/v1/items?limit=100&updated_since=2026-11-01T00:00:00Z

{ "data": [ {
    "id": "6f2c…", "title": "Vintage brass desk lamp", "description": "…", "status": "active",
    "sku": "LAMP-12", "price": 85, "currency": "USD", "quantity": 1, "condition": "used",
    "location": "Shelf B3", "images": ["https://…"], "cost": 12.5,
    "sold_at": null, "sold_price": null, "created_at": "…", "updated_at": "…",
    "listings": [ { "marketplace": "ebay", "listing_id": "1234…", "url": "https://…", "status": "active", "price": 85 } ]
  } ],
  "next_cursor": "WyIyMDI2…" }

GET /items/{id}

One item in the same shape, or 404.

GET /orders

Sales across every marketplace, newest first. Needs orders.read. Query: limit, cursor, since.

GET https://crossflo.io/api/v1/orders?since=2026-11-01T00:00:00Z

{ "data": [ { "id": "…", "item_id": "6f2c…", "marketplace": "fairclose", "order_number": "FC-1042",
    "item_title": "Vintage brass desk lamp", "buyer_name": "J. Smith", "sale_price": 80,
    "shipping_charged": 12, "fees": 6.4, "currency": "USD", "quantity": 1, "status": "shipped",
    "ordered_at": "…", "shipped_at": "…", "delivered_at": null, "returned": false } ],
  "next_cursor": null }

Pagination

Lists return next_cursor. Pass it back as cursor until it's null. Cursors are stable while you page; don't build them yourself.

Rate limits

PlanUSD pricingPer minutePer day (UTC)Page size
StarterFree602,00050
Premium$49/month · $490/year30025,000200
Commercial$199/month · $1,990/year1,200150,000500
EnterpriseContact usCustom limits and SLA · no self-serve checkout

API billing is per app and separate from seller subscriptions. Paid checkout needs admin upgrade approval. No overage charges. Cancellation takes effect at period end; failed payment has seven days grace. Test checkout does not change live API limits.

Every response has X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Day and X-RateLimit-Remaining-Day. Over a limit: HTTP 429 with Retry-After (seconds). Back off; don't retry in a loop.

Errors

{ "error": { "code": "insufficient_permission", "message": "This app wasn't approved for orders.read…" } }
  • 401 unauthorized / invalid_token — missing, expired or revoked token. Refresh, or ask the seller to connect again.
  • 403 not_an_app_token — use a token issued to your app, not a website session.
  • 403 app_not_approved — your app is pending, rejected or suspended.
  • 403 personal_app — personal apps only work with their owner's account.
  • 403 insufficient_permission — the app doesn't have that permission.
  • 404 not_found — no such item (or not this seller's).
  • 429 rate_limited — wait for Retry-After.
  • 5xx — try again later with backoff.

Security checklist

  • Always use PKCE and a fresh random state; check it on return.
  • Register exact redirect URIs (no wildcards). https only, except http://localhost for personal apps.
  • Keep the client secret and refresh tokens server side; never ship them in a browser or mobile app.
  • Store as little seller data as you need, and delete it when they disconnect.
  • Never ask sellers for their Crossflo password.

Changelog

  • 2026-11-18 — v1: Sign in with Crossflo, /me, /items, /items/{id}, /orders; Starter, Premium and Commercial plans.

Questions or need a higher limit? Contact developer support.