Freeport Seller API

The sandbox

sandbox-api.freeport.gg is the whole marketplace on its own database with a fake payment provider. Register on sandbox.freeport.gg and you are a seller on arrival: the sandbox approves the profile as it makes it, and fp_test_ keys mint from Integrations without an application. Everything else is production's code, so what works here works there with a different host and key.

The sandbox is switched on when a seller asks for API access, not left running. Write to support@freeport.gg to have it started. Until it is, sandbox-api.freeport.gg does not answer, which is the sandbox being off and not a fault in your client.

The synthetic buyer

There is no one else on the sandbox to buy from you, so the API does. Every route here is a 404 anywhere but the sandbox, and acts only as the synthetic buyer, never as a person who bought from you there:

  • POST /v1/sandbox/orders with { "listing_id", "quantity" }: the buyer places and pays for an order through the real checkout. Your endpoint receives order.paid by the production path, with the same body it would carry live.
  • POST /v1/sandbox/orders/{id}/confirm: the buyer confirms delivery. Only after you have accepted and delivered; the money moves to your pending balance.
  • POST /v1/sandbox/orders/{id}/cancel: the buyer cancels before you accept, which is their right; you receive order.cancelled.
  • POST /v1/sandbox/orders/{id}/dispute: the buyer opens a dispute with a reason. Then rehearse the rest from both sides: your own dispute routes with /sandbox in front act as the buyer (/dispute/statements, /dispute/offers, /dispute/offers/{offerId}/accept, /decline, /withdraw and /dispute/release). See Disputes.
  • POST /v1/sandbox/reset: your listings off the shelf, your syncs and deliveries gone, your outbox cleared. Keys and endpoints stay; so do orders, because the ledger under them is append-only.

What resets

The whole sandbox can be rebuilt at any time from an empty database and a seeded catalog, without notice. Accounts, keys, listings and orders go with it, so keep the script that sets yours up, and expect the catalog's ids to change while its slugs do not. That is the one place the sandbox is stricter than production, on purpose: an integration that keys on ids it read once will break here first.

What is missing

Real money, real buyers, real time. The accept and delivery clocks run at their real lengths, so a test that waits for an expiry waits thirty minutes; decline instead. Mail from the sandbox goes to the address you registered with, and nowhere else.