Orders and chat

An order is paid before you ever see it: SafeHarbour holds the buyer's money, you accept within thirty minutes, deliver within twice your promised time, the buyer confirms (or three days pass), and the money is released. Your software's job is the middle: hear about it, accept it, deliver it, talk to the buyer if needed.

Hearing about it

Three ways, from best to worst:

• Webhooks. Subscribe to order.paid and the rest; the body carries the order exactly as GET /v1/orders/{id} returns it. See Webhooks.
• The change token. GET /v1/orders/changes answers with an ETag. Poll it with If-None-Match every few seconds: a 304 costs nothing on either side, a 200 means something moved and it is time to read the feed. Never poll the feed itself in a loop.
• The feed. GET /v1/orders?state=paid pages your book newest first; ?updated_since= walks everything that changed after a moment, oldest first, for a catch-up after downtime.

What an order carries

Everything a deliverer needs and nothing they do not: the listing and your external id for it, the quantity, the realm with its region and faction, the buyer's character name or player id, the money split (subtotal, your fee, your net), the deadlines, the state and the sequence number of the last event. For an account order the buyer's credentials go through POST /v1/orders/{id}/credentials, encrypted, never through chat.

The three moves

• POST /v1/orders/{id}/accept: you have seen it and will deliver. The delivery clock starts.
• POST /v1/orders/{id}/deliver: the goods are with the buyer. Their confirm clock starts. On an account order the credentials must be stored first.
• POST /v1/orders/{id}/decline: you cannot fill it. The buyer is refunded in full and your stock is restored. Better than an expiry, which costs reliability.

Every move answers with the order after it. A move the state machine forbids is a 409 with illegal_transition; the order's current state is in the body, so a tool that raced a buyer's cancel learns what happened in one round trip.

Chat

GET /v1/orders/{id}/messages is the thread, oldest first; POST adds your words. The buyer's and the system's messages arrive as order.message events, never your own. Chat is read by staff during a dispute, and is scanned for attempts to move a trade off the platform, so keep it to the delivery.

Disputes and refunds

A buyer who did not receive what they paid for opens a dispute; you receive order.disputed, then order.dispute_resolved with the outcome and, where money moved, order.refunded. A refund restores stock. None of this needs your software to do anything but know, and it should know: a farm with a dispute rate is a farm that is about to be asked about it.