Shop API

List active orders

Read unfinished orders and open disputes for your shop.

List active orders for the shop attached to your API key. Active means unfinished orders and orders with an open dispute, matching the Superpanel delivery list. Cancelled orders and completed orders without an open dispute are excluded.

Endpoint and authentication

GET https://popbob.gg/api/v1/orders

Send a bearer token with the orders:read permission. Create a new key in Superpanel with “Read active orders” selected if your current key does not have it. The shop is taken from the key; you cannot select another shop in the request.

curl 'https://popbob.gg/api/v1/orders?limit=100' \
  -H 'Authorization: Bearer pb_live_your_key_here'

Pagination

limit defaults to 100 and must be an integer from 1 to 100. Results are ordered oldest first by creation time, with the order ID breaking ties. When hasMore is true, passnextCursor as the URL-encoded after query parameter to get the next page. Keep the cursor unchanged.

The final page has hasMore: false andnextCursor: null. An empty shop returns an emptyorders array. Pages reflect current state, so an order that is completed or cancelled between requests may disappear. Start without after when reconciling the full active list.

Bot loading and live updates

Fetch every page when your bot starts and after reconnecting to reconcile its active orders. This endpoint returns the current list. Its after cursor only paginates that list; it cannot track later order changes. Do not poll it on a timer.

Connect to the API WebSocket with your key in the Authorization header. orders:read enables order events; add messages:read to receive chat messages on the same connection. Each connection is automatically subscribed to its key's shop and permitted streams.

wss://popbob.gg/api/ws/shop-api
Authorization: Bearer pb_live_your_key_here

The connection sends ready after subscribing:

{
  "t": "event",
  "e": "ready",
  "d": { "shopId": "your-shop-id", "scopes": ["orders:read"] }
}

Committed order changes send one of these signals. They cover marketplace, forum, and auction orders:

order:new: an order was created.
order:updated: order details, priority, redelivery, or dispute status changed.
order:completed: a completion date was recorded.
order:cancelled: an order was archived after cancellation.

{
  "t": "event",
  "e": "order:new",
  "d": { "shopId": "your-shop-id", "orderId": "order_123" }
}

These signals contain only identifiers. Refetch the active list to obtain current order details. An order can change again before a signal arrives, and multiple signals can refer to the same order. Use the fetched list as the source of truth rather than applying an event name as a state change.

Connect the socket and handle order signals immediately.
After ready, fetch every order page, starting without after.
On an order signal, refresh the list. Coalesce signals into one refresh at a time. If a signal arrives during a refresh, fetch again before using that list for delivery decisions.
After a disconnect, reconnect with backoff and repeat the full load. Discard fetch results from the previous connection. Order cursors do not replay missed events.

Fetches are triggered by connection readiness and order signals, with no recurring timer. Keep refresh work pending when rate limited and retry after Retry-After; incoming signals should not start parallel retries. Track delivery work durably so repeated signals or reconnects do not repeat a delivery.

Revoked or expired keys, removed read permissions, and shop or owner bans stop event delivery. Slow connections close with code1013. An order-stream reset can close with1012; reconnect and reload the active list. Connecting a bot does not mark the shop or owner online.

Successful response

{
  "orders": [
    {
      "id": "order_123",
      "userId": "customer_username",
      "username": "MinecraftPlayer",
      "game": "donutsmp",
      "created": "2026-11-05T15:59:00.000Z",
      "completed": null,
      "disputeStatus": null,
      "deliveryMethod": "Specified",
      "scheduledDate": null,
      "coords": [100, 64, 200],
      "requestedCoords": [100, 64, 200],
      "priority": "Normal",
      "payoutCents": "500",
      "note": "",
      "cart": [
        {
          "id": "67f15e3c3d6d55ab781ac123",
          "name": "Diamonds",
          "quantity": 64,
          "attributes": {}
        }
      ]
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Use id with the Complete an order endpoint. userId is the Popbob account ID accepted by the messaging endpoints; username is the in-game name. These may be null when unavailable. Cart IDs are product IDs. Dates use ISO 8601. Orders with an open dispute can already have a completion date and cannot be completed again through the API.

payoutCents is the shop's earnings in USD cents, returned as a string, or null if no payout was recorded. It excludes the platform's share and is not the customer's payment total.

Errors and limits

Invalid limits or cursors return 400. Missing, invalid, expired, or revoked keys return 401. Keys withoutorders:read return 403. Authentication configuration failures return 503 and unexpected server failures return 500. Error bodies contain anerror string.

Requests share the usual limit of 60 requests per API key per minute with the other Shop API endpoints. Exceeding it returns429 and a Retry-After header in seconds. See the Shop API overview for details.