{ "openapi": "3.1.0", "info": { "title": "Freeport Seller API", "version": "2026-09-09", "description": "One API for every lane and every kind of seller software.\n\nSend your key as `Authorization: Bearer fp_live_…`. Money is a decimal string in the row's currency, ids are prefixed ULIDs, times are ISO 8601 UTC. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`; a 429 carries `Retry-After`. Errors are `{ \"error\": { \"code\", \"message\", \"requestId\" } }`." }, "servers": [ { "url": "https://api.freeport.gg" } ], "tags": [ { "name": "Meta", "description": "The document, and the key looking at it." }, { "name": "Account", "description": "The seller behind the key." }, { "name": "Catalog", "description": "Games, lanes, realms and packages, by id and slug." }, { "name": "Listings", "description": "Your stock on the shelf." }, { "name": "Orders", "description": "The order feed and the three moves a seller makes." }, { "name": "Chat", "description": "The thread with the buyer." }, { "name": "Boosting", "description": "Your price curves on the services the platform standardises." }, { "name": "Stock syncs", "description": "A whole sheet of stock, landed as one decision." }, { "name": "Webhooks", "description": "Where events go, signed, retried, logged." }, { "name": "Sandbox", "description": "The synthetic buyer, on the sandbox only." } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "fp_live_… on production, fp_test_… on the sandbox" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, snake_case. What a client branches on." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "Quote this when asking for help." }, "details": { "description": "Field-level detail where there is any." } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Ping": { "type": "object", "properties": { "ok": { "type": "boolean" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "server_time": { "type": "string", "format": "date-time" }, "key": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "label": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "catalog:read", "listings:read", "listings:write", "orders:read", "orders:write", "chat:read", "chat:write", "account:read", "account:write", "webhooks:manage" ] } }, "ip_allowlist": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "label", "scopes", "ip_allowlist", "expires_at", "created_at" ], "additionalProperties": false }, "seller": { "type": "object", "properties": { "handle": { "type": "string" }, "tier": { "type": "string", "enum": [ "new", "standard", "trusted" ] }, "trading_status": { "type": "string" }, "holiday_mode": { "type": "boolean" } }, "required": [ "handle", "tier", "trading_status", "holiday_mode" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "reads_per_minute": { "type": "integer" }, "writes_per_minute": { "type": "integer" }, "bulk_per_minute": { "type": "integer" }, "chat_per_minute": { "type": "integer" } }, "required": [ "reads_per_minute", "writes_per_minute", "bulk_per_minute", "chat_per_minute" ], "additionalProperties": false } }, "required": [ "ok", "environment", "server_time", "key", "seller", "limits" ], "additionalProperties": false }, "Me": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "handle": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "tier": { "type": "string", "enum": [ "new", "standard", "trusted" ] }, "trading_status": { "type": "string", "description": "`active`, or `suspended`: reads keep working, writes that start something are refused." }, "holiday_mode": { "type": "boolean" }, "presence": { "type": "string", "enum": [ "online", "away", "offline" ] }, "payout_hold_days": { "type": "integer" }, "qualifying_orders": { "type": "integer" } }, "required": [ "id", "handle", "display_name", "tier", "trading_status", "holiday_mode", "presence", "payout_hold_days", "qualifying_orders" ], "additionalProperties": false }, "Balance": { "type": "object", "properties": { "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "available": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "pending": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "payout_hold_days": { "type": "integer" } }, "required": [ "currency", "available", "pending", "payout_hold_days" ], "additionalProperties": false }, "FeeQuote": { "type": "object", "properties": { "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "category": { "type": "string" }, "subtotal": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "buyer_fee": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "buyer_total": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "seller_fee": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "seller_fee_bps": { "type": "integer" }, "reserve": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "seller_net": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." } }, "required": [ "currency", "category", "subtotal", "buyer_fee", "buyer_total", "seller_fee", "seller_fee_bps", "reserve", "seller_net" ], "additionalProperties": false }, "Game": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "slug", "name", "platform", "updated_at" ], "additionalProperties": false }, "GameDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "currency", "item", "account", "service", "topup", "giftcard" ] }, "vocabulary": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "label", "options" ], "additionalProperties": false } }, "packages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": [ "integer", "null" ] }, "unit": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "popular": { "type": "boolean" } }, "required": [ "id", "slug", "label", "amount", "unit", "region", "popular" ], "additionalProperties": false } } }, "required": [ "id", "slug", "name", "kind", "vocabulary", "packages" ], "additionalProperties": false } }, "servers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "name": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "faction": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "slug", "name", "region", "faction", "attributes" ], "additionalProperties": false } } }, "required": [ "id", "slug", "name", "platform", "updated_at", "categories", "servers" ], "additionalProperties": false }, "Candidate": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "name": { "type": "string" }, "score": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "id", "slug", "name", "score" ], "additionalProperties": false }, "Resolution": { "type": "object", "properties": { "game": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" } }, "category": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" } }, "server": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" } } }, "required": [ "game", "category", "server" ], "additionalProperties": false }, "Tier": { "type": "object", "properties": { "min_qty": { "type": "integer", "description": "From this order quantity up, in units." }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." } }, "required": [ "min_qty", "price" ], "additionalProperties": false }, "CatalogChanges": { "type": "object", "properties": { "changes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "game", "category", "server", "package" ] }, "action": { "type": "string", "enum": [ "created", "updated" ] }, "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "name": { "type": "string" }, "game_id": { "type": [ "string", "null" ], "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "type", "action", "id", "slug", "name", "game_id", "updated_at" ], "additionalProperties": false } }, "next_since": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "changes", "next_since" ], "additionalProperties": false }, "Listing": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "external_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "removed" ] }, "taken_down": { "type": "boolean" }, "game": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "slug", "name" ], "additionalProperties": false }, "category": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "id", "slug", "name", "kind" ], "additionalProperties": false }, "server": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "name": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "faction": { "type": [ "string", "null" ] } }, "required": [ "id", "slug", "name", "region", "faction" ], "additionalProperties": false }, "package": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "slug", "label" ], "additionalProperties": false }, "path": { "type": "string", "description": "The catalog page the listing appears on." }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/Tier" } }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "price_per_qty": { "type": "integer", "description": "How many units the price buys, for example 1000 gold." }, "unit_label": { "type": "string" }, "min_qty": { "type": "integer" }, "max_qty": { "type": [ "integer", "null" ] }, "stock_qty": { "type": "integer" }, "low_stock_alert_qty": { "type": [ "integer", "null" ] }, "delivery_eta_minutes": { "type": "integer" }, "attributes": { "type": "object", "additionalProperties": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "external_id", "status", "taken_down", "game", "category", "server", "package", "path", "title", "description", "price", "tiers", "currency", "price_per_qty", "unit_label", "min_qty", "max_qty", "stock_qty", "low_stock_alert_qty", "delivery_eta_minutes", "attributes", "created_at", "updated_at" ], "additionalProperties": false }, "Order": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "state": { "type": "string", "enum": [ "draft", "payment_pending", "paid", "accepted", "delivering", "delivered", "disputed", "completed", "cancelled", "expired", "refunded", "partially_refunded" ] }, "state_updated_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "listing": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "external_id": { "type": [ "string", "null" ] }, "title": { "type": "string" } }, "required": [ "id", "external_id", "title" ], "additionalProperties": false }, "boost": { "type": [ "object", "null" ], "properties": { "offer_id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "config": { "type": [ "object", "null" ] } }, "required": [ "offer_id", "config" ], "additionalProperties": false }, "game": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "server": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "faction": { "type": [ "string", "null" ] } }, "required": [ "slug", "name", "faction" ], "additionalProperties": false }, "category_kind": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unit_label": { "type": [ "string", "null" ] }, "price_per_qty": { "type": "integer" }, "unit_price": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "subtotal": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "buyer_fee": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "seller_fee": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "total": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "buyer": { "type": "object", "properties": { "handle": { "type": [ "string", "null" ] }, "character_name": { "type": [ "string", "null" ] } }, "required": [ "handle", "character_name" ], "additionalProperties": false }, "deadlines": { "type": "object", "properties": { "accept_by": { "type": [ "string", "null" ], "format": "date-time" }, "deliver_by": { "type": [ "string", "null" ], "format": "date-time" }, "auto_confirm_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "accept_by", "deliver_by", "auto_confirm_at" ], "additionalProperties": false }, "fee_schedule_ids": { "type": "object", "properties": { "buyer": { "type": [ "string", "null" ], "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "seller": { "type": [ "string", "null" ], "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" } }, "required": [ "buyer", "seller" ], "additionalProperties": false } }, "required": [ "id", "state", "state_updated_at", "created_at", "listing", "boost", "game", "server", "category_kind", "quantity", "unit_label", "price_per_qty", "unit_price", "subtotal", "buyer_fee", "seller_fee", "total", "currency", "buyer", "deadlines", "fee_schedule_ids" ], "additionalProperties": false }, "OrderEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "seq": { "type": "integer", "description": "Strictly increasing per order; the number a webhook consumer keys on." }, "type": { "type": "string" }, "from_state": { "type": [ "string", "null" ], "enum": [ "draft", "payment_pending", "paid", "accepted", "delivering", "delivered", "disputed", "completed", "cancelled", "expired", "refunded", "partially_refunded" ] }, "to_state": { "type": [ "string", "null" ], "enum": [ "draft", "payment_pending", "paid", "accepted", "delivering", "delivered", "disputed", "completed", "cancelled", "expired", "refunded", "partially_refunded" ] }, "actor": { "type": "string", "enum": [ "user", "admin", "system" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "seq", "type", "from_state", "to_state", "actor", "created_at" ], "additionalProperties": false }, "OrderChanges": { "type": "object", "properties": { "changed": { "type": "boolean" }, "counts": { "type": "object", "additionalProperties": true } }, "required": [ "changed", "counts" ], "additionalProperties": false }, "Message": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "body": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "author": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "seller", "buyer", "system" ] }, "handle": { "type": [ "string", "null" ] } }, "required": [ "role", "handle" ], "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "body", "image", "author", "created_at" ], "additionalProperties": false }, "MessagePosted": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "created_at": { "type": "string", "format": "date-time" }, "warnings": { "type": "array", "items": { "type": "string", "description": "Contact-detection notices, returned to the sender." } } }, "required": [ "id", "created_at", "warnings" ], "additionalProperties": false }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "url": { "type": "string", "format": "uri" }, "label": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.paid", "order.accepted", "order.delivering", "order.delivered", "order.completed", "order.cancelled", "order.refunded", "order.expired", "order.disputed", "order.dispute_resolved", "order.message", "listing.low_stock", "listing.sold_out", "listing.taken_down", "listing.reinstated", "account.trading_status_changed", "ping" ] } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "failing_since": { "type": [ "string", "null" ], "format": "date-time" }, "previous_secret_until": { "type": [ "string", "null" ], "format": "date-time", "description": "While set, deliveries carry a second signature made with the secret before the last rotation." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "label", "events", "status", "disabled_reason", "failing_since", "previous_secret_until", "created_at", "updated_at" ], "additionalProperties": false }, "WebhookWithSecret": { "type": "object", "properties": { "secret": { "type": "string", "description": "Shown once. Verify every delivery with it.", "example": "whsec_…" }, "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "url": { "type": "string", "format": "uri" }, "label": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.paid", "order.accepted", "order.delivering", "order.delivered", "order.completed", "order.cancelled", "order.refunded", "order.expired", "order.disputed", "order.dispute_resolved", "order.message", "listing.low_stock", "listing.sold_out", "listing.taken_down", "listing.reinstated", "account.trading_status_changed", "ping" ] } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "failing_since": { "type": [ "string", "null" ], "format": "date-time" }, "previous_secret_until": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "secret", "id", "url", "label", "events", "status", "disabled_reason", "failing_since", "previous_secret_until", "created_at", "updated_at" ], "additionalProperties": false }, "Delivery": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "event_id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "event_type": { "type": "string", "enum": [ "order.paid", "order.accepted", "order.delivering", "order.delivered", "order.completed", "order.cancelled", "order.refunded", "order.expired", "order.disputed", "order.dispute_resolved", "order.message", "listing.low_stock", "listing.sold_out", "listing.taken_down", "listing.reinstated", "account.trading_status_changed", "ping" ] }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "exhausted" ] }, "attempts": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "response_status": { "type": [ "integer", "null" ] }, "response_snippet": { "type": [ "string", "null" ], "description": "The first kilobyte of what your server answered." }, "last_error": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "event_id", "event_type", "status", "attempts", "next_attempt_at", "last_attempt_at", "response_status", "response_snippet", "last_error", "duration_ms", "created_at" ], "additionalProperties": false }, "Queued": { "type": "object", "properties": { "queued": { "type": "boolean" } }, "required": [ "queued" ], "additionalProperties": false }, "CodeVault": { "type": "object", "properties": { "available": { "type": "integer", "description": "Unsold, on the shelf. Also the listing stock the vault maintains." }, "delivered": { "type": "integer" }, "withdrawn": { "type": "integer" } }, "required": [ "available", "delivered", "withdrawn" ], "additionalProperties": false }, "CodeVaultAdded": { "type": "object", "properties": { "added": { "type": "integer" }, "duplicates": { "type": "integer" }, "available": { "type": "integer" }, "delivered": { "type": "integer" }, "withdrawn": { "type": "integer" } }, "required": [ "added", "duplicates", "available", "delivered", "withdrawn" ], "additionalProperties": false }, "CodeVaultWithdrawn": { "type": "object", "properties": { "removed": { "type": "integer" }, "available": { "type": "integer" }, "delivered": { "type": "integer" }, "withdrawn": { "type": "integer" } }, "required": [ "removed", "available", "delivered", "withdrawn" ], "additionalProperties": false }, "BoostOption": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "range", "number", "choice", "flags" ] }, "min": { "type": "integer" }, "max": { "type": "integer" }, "unit": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } }, "flags": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "key", "label", "type" ], "additionalProperties": false }, "BoostTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "slug": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/BoostOption" } }, "offer_id": { "type": [ "string", "null" ], "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" } }, "required": [ "id", "slug", "name", "category", "options", "offer_id" ], "additionalProperties": false }, "BoostPricing": { "type": "object", "properties": { "base": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "per_unit": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." }, "description": "A rate per unit, keyed by a range or number option." }, "choice_bps": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer" } }, "description": "Basis points per chosen value, keyed by a choice option then its value." }, "flag_bps": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Basis points per extra offered. An extra missing here is not for sale." }, "min_total": { "type": [ "string", "null" ], "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." } }, "required": [ "base", "per_unit", "choice_bps", "flag_bps", "min_total" ], "additionalProperties": false }, "BoostOffer": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "template": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "name": { "type": "string" }, "category": { "type": "string" }, "game": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ], "additionalProperties": false } }, "required": [ "id", "name", "category", "game" ], "additionalProperties": false }, "pricing": { "$ref": "#/components/schemas/BoostPricing" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "eta_hours": { "type": "integer" }, "from_price": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "A decimal string in the row's currency. Never a float." } }, "required": [ "id", "status", "template", "pricing", "currency", "eta_hours", "from_price" ], "additionalProperties": false }, "StockSync": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "mode": { "type": "string", "enum": [ "replace", "merge" ] }, "status": { "type": "string", "enum": [ "open", "committing", "committed", "expired", "failed" ] }, "line_count": { "type": "integer" }, "summary": { "type": [ "object", "null" ], "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" }, "paused": { "type": "integer" }, "failed": { "type": "integer" } }, "required": [ "created", "updated", "unchanged", "paused", "failed" ], "additionalProperties": false }, "error": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "An open sync not committed by then expires." }, "committed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "mode", "status", "line_count", "summary", "error", "expires_at", "committed_at", "created_at", "updated_at" ], "additionalProperties": false }, "StagingResult": { "type": "object", "properties": { "external_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "staged", "invalid" ] }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "external_id", "status" ], "additionalProperties": false }, "Staged": { "type": "object", "properties": { "sync": { "$ref": "#/components/schemas/StockSync" }, "staged": { "type": "integer" }, "invalid": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/StagingResult" } } }, "required": [ "sync", "staged", "invalid", "results" ], "additionalProperties": false }, "SyncLine": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "external_id": { "type": "string" }, "listing_id": { "type": [ "string", "null" ], "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "action": { "type": [ "string", "null" ], "enum": [ "created", "updated", "unchanged", "paused", "failed" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, "line": { "type": "object", "additionalProperties": true, "description": "The line as staged." } }, "required": [ "id", "external_id", "listing_id", "action", "error", "line" ], "additionalProperties": false }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "A prefixed ULID", "example": "lst_01J9ZQ2K9V3XW7NBRTM4C6D8EF" }, "type": { "type": "string", "enum": [ "order.paid", "order.accepted", "order.delivering", "order.delivered", "order.completed", "order.cancelled", "order.refunded", "order.expired", "order.disputed", "order.dispute_resolved", "order.message", "listing.low_stock", "listing.sold_out", "listing.taken_down", "listing.reinstated", "account.trading_status_changed", "ping" ] }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string" }, "data": { "type": "object", "description": "For order.* the order as GET /v1/orders/{id} returns it under `order`; for listing.* the listing under `listing`; for order.message the message under `message`.", "additionalProperties": true } }, "required": [ "id", "type", "created_at", "api_version", "data" ], "additionalProperties": false } } }, "paths": { "/v1/sandbox/orders": { "post": { "tags": [ "Sandbox" ], "x-sandbox-only": true, "x-scope": "orders:write", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Buy from yourself", "description": "The synthetic buyer places and pays for an order on one of your listings through the real checkout, so `order.paid` reaches your endpoint by the production path. Then accept and deliver it as you would any order, and drive the buyer from the routes below. Sandbox only.\n\nScope `orders:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1SandboxOrders", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listing_id": { "type": "string", "minLength": 1, "maxLength": 64 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "character_name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "listing_id", "quantity" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "The order, paid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sandbox/orders/{id}/confirm": { "post": { "tags": [ "Sandbox" ], "x-sandbox-only": true, "x-scope": "orders:write", "x-rate-limit-bucket": "writes", "summary": "The buyer confirms delivery", "description": "Scope `orders:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1SandboxOrdersConfirm", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The order, completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sandbox/orders/{id}/cancel": { "post": { "tags": [ "Sandbox" ], "x-sandbox-only": true, "x-scope": "orders:write", "x-rate-limit-bucket": "writes", "summary": "The buyer cancels before you accept", "description": "Scope `orders:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1SandboxOrdersCancel", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The order, refunded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sandbox/orders/{id}/dispute": { "post": { "tags": [ "Sandbox" ], "x-sandbox-only": true, "x-scope": "orders:write", "x-rate-limit-bucket": "writes", "summary": "The buyer opens a dispute", "description": "Scope `orders:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1SandboxOrdersDispute", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason_code": { "type": "string", "enum": [ "not_delivered", "partially_delivered", "wrong_item", "recalled", "other" ], "default": "not_delivered" }, "detail": { "type": "string", "minLength": 10, "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The order, disputed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sandbox/reset": { "post": { "tags": [ "Sandbox" ], "x-sandbox-only": true, "x-scope": "account:write", "x-rate-limit-bucket": "bulk", "summary": "Wipe your slate", "description": "Listings off the shelf, syncs and deliveries gone, the outbox cleared. Keys and endpoints stay; orders stay, because the ledger under them is append-only.\n\nScope `account:write`. Spends the `bulk` budget (20 a minute for a new seller).", "operationId": "postV1SandboxReset", "parameters": [], "responses": { "200": { "description": "What went", "content": { "application/json": { "schema": { "type": "object", "properties": { "listings_removed": { "type": "integer" }, "syncs_deleted": { "type": "integer" }, "deliveries_deleted": { "type": "integer" }, "events_deleted": { "type": "integer" } }, "required": [ "listings_removed", "syncs_deleted", "deliveries_deleted", "events_deleted" ], "additionalProperties": false } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/openapi.json": { "get": { "tags": [ "Meta" ], "summary": "This document", "description": "No key needed.", "operationId": "getV1OpenapiJson", "security": [], "parameters": [], "responses": { "200": { "description": "The OpenAPI document" } } } }, "/v1/ping": { "get": { "tags": [ "Meta" ], "x-rate-limit-bucket": "reads", "summary": "Is this key alive, what can it do, where are its limits", "description": "Any key. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1Ping", "parameters": [], "responses": { "200": { "description": "The key, the seller and the budgets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ping" } } } }, "401": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/me/balance": { "get": { "tags": [ "Account" ], "x-scope": "account:read", "x-rate-limit-bucket": "reads", "summary": "Your balance", "description": "Summed from the ledger, never stored: what is spendable now, and what is still held while orders complete and the payout hold runs.\n\nScope `account:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1MeBalance", "parameters": [], "responses": { "200": { "description": "The balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/fees/quote": { "get": { "tags": [ "Account" ], "x-rate-limit-bucket": "reads", "summary": "What an order would cost", "description": "Priced by the same resolver as checkout. The seller side is exact; the buyer side leaves out the first-order waiver, since which buyer is unknown. A tool pricing across marketplaces wants this before it lists, not after the first sale.\n\nAny key. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1FeesQuote", "parameters": [ { "name": "category", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "currency", "item", "account", "service", "topup", "giftcard" ] } }, { "name": "subtotal", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "minLength": 3, "maxLength": 3, "default": "USD" } }, { "name": "game", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "The quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeQuote" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/me": { "get": { "tags": [ "Account" ], "x-scope": "account:read", "x-rate-limit-bucket": "reads", "summary": "The seller behind the key", "description": "Scope `account:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1Me", "parameters": [], "responses": { "200": { "description": "The seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Account" ], "x-scope": "account:write", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Holiday mode on or off", "description": "Holiday mode hides every listing at once: the switch a farm flips when the deliverers go home.\n\nScope `account:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "patchV1Me", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "holiday_mode": { "type": "boolean" }, "presence": { "type": "string", "enum": [ "online", "offline" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The seller, after the change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/catalog/games": { "get": { "tags": [ "Catalog" ], "x-rate-limit-bucket": "reads", "x-conditional": true, "summary": "Every active game", "description": "Any key. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1CatalogGames", "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The ETag from the previous answer. A match is a 304 with no body." } ], "responses": { "200": { "description": "Games, most popular first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Game" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "304": { "description": "Unchanged since the ETag you sent" }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/catalog/games/{slug}": { "get": { "tags": [ "Catalog" ], "x-rate-limit-bucket": "reads", "x-conditional": true, "summary": "One game: lanes, realms with faction, packages, vocabulary", "description": "Any key. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1CatalogGames", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The ETag from the previous answer. A match is a 304 with no body." } ], "responses": { "200": { "description": "The game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GameDetail" } } } }, "304": { "description": "Unchanged" }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/catalog/resolve": { "post": { "tags": [ "Catalog" ], "x-rate-limit-bucket": "reads", "summary": "Your names to our ids", "description": "Ranks games, categories and servers against the names you keep. A named faction is decisive on a realm. Never creates anything.\n\nAny key. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "postV1CatalogResolve", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "game": { "type": "string", "minLength": 1, "maxLength": 80 }, "category": { "type": "string", "minLength": 1, "maxLength": 80 }, "server": { "type": "string", "minLength": 1, "maxLength": 80 }, "faction": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "game" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Up to five candidates each, best first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resolution" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/catalog/changes": { "get": { "tags": [ "Catalog" ], "x-rate-limit-bucket": "reads", "summary": "Games, lanes, realms and packages added or renamed since a moment", "description": "Any key. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1CatalogChanges", "parameters": [ { "name": "since", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } } ], "responses": { "200": { "description": "Oldest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogChanges" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/listings": { "get": { "tags": [ "Listings" ], "x-scope": "listings:read", "x-rate-limit-bucket": "reads", "summary": "Your listings", "description": "Scope `listings:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1Listings", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "active", "paused", "removed" ] } }, { "name": "game", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Newest change first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Listing" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass back as ?cursor= for the next page. Null on the last page." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Listings" ], "x-scope": "listings:write", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Create a listing", "description": "Game, category, server and package by our id or our slug. The title is generated when absent.\n\nScope `listings:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1Listings", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "game": { "type": "string", "minLength": 1, "maxLength": 64 }, "category": { "type": "string", "minLength": 1, "maxLength": 64 }, "server": { "type": "string", "minLength": 1, "maxLength": 64 }, "package": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string", "minLength": 4, "maxLength": 120 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "min_qty": { "type": "integer", "minimum": 2, "maximum": 1000000 }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" } }, "required": [ "min_qty", "price" ], "additionalProperties": false }, "maxItems": 3 }, "description": { "type": "string", "maxLength": 2000 }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "USD" }, "unit_label": { "type": "string", "minLength": 1, "maxLength": 40, "default": "unit" }, "price_per_qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "min_qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "max_qty": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "stock_qty": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 0 }, "low_stock_alert_qty": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "delivery_eta_minutes": { "type": "integer", "minimum": 1, "maximum": 20160, "default": 60 }, "attributes": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 80 } }, "external_id": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "draft", "active" ], "default": "active" } }, "required": [ "game", "category", "price" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listing" } } } }, "400": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/listings/batch": { "post": { "tags": [ "Stock syncs" ], "x-scope": "listings:write", "x-rate-limit-bucket": "bulk", "summary": "Up to a thousand lines in one call", "description": "The sync engine in merge mode, opened, staged and committed for you. Answers at once with a result per line for the staging; poll the sync for the result per line of the apply.\n\nScope `listings:write`. Spends the `bulk` budget (20 a minute for a new seller).", "operationId": "postV1ListingsBatch", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "game": { "type": "string", "minLength": 1, "maxLength": 64 }, "category": { "type": "string", "minLength": 1, "maxLength": 64 }, "server": { "type": "string", "minLength": 1, "maxLength": 64 }, "package": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string", "minLength": 4, "maxLength": 120 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "min_qty": { "type": "integer", "minimum": 2, "maximum": 1000000 }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" } }, "required": [ "min_qty", "price" ], "additionalProperties": false }, "maxItems": 3 }, "description": { "type": "string", "maxLength": 2000 }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "USD" }, "unit_label": { "type": "string", "minLength": 1, "maxLength": 40, "default": "unit" }, "price_per_qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "min_qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "max_qty": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "stock_qty": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 0 }, "low_stock_alert_qty": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "delivery_eta_minutes": { "type": "integer", "minimum": 1, "maximum": 20160, "default": 60 }, "attributes": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 80 } }, "external_id": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "draft", "active", "paused" ], "default": "active" } }, "required": [ "game", "category", "price", "external_id" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 } }, "required": [ "lines" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Staged and committed; the worker applies it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Staged" } } } }, "400": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/listings/by-external-id/{externalId}": { "put": { "tags": [ "Listings" ], "x-scope": "listings:write", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Create or update by your own id for the line", "description": "Creates on first sight, updates after. A listing never moves to another game, category, server or package: that is a new external id.\n\nScope `listings:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "putV1ListingsByExternalId", "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "game": { "type": "string", "minLength": 1, "maxLength": 64 }, "category": { "type": "string", "minLength": 1, "maxLength": 64 }, "server": { "type": "string", "minLength": 1, "maxLength": 64 }, "package": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string", "minLength": 4, "maxLength": 120 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "min_qty": { "type": "integer", "minimum": 2, "maximum": 1000000 }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" } }, "required": [ "min_qty", "price" ], "additionalProperties": false }, "maxItems": 3 }, "description": { "type": "string", "maxLength": 2000 }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "USD" }, "unit_label": { "type": "string", "minLength": 1, "maxLength": 40, "default": "unit" }, "price_per_qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "min_qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "max_qty": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "stock_qty": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 0 }, "low_stock_alert_qty": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "delivery_eta_minutes": { "type": "integer", "minimum": 1, "maximum": 20160, "default": 60 }, "attributes": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 80 } }, "external_id": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "draft", "active" ], "default": "active" } }, "required": [ "game", "category", "price" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listing" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listing" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/listings/{id}": { "get": { "tags": [ "Listings" ], "x-scope": "listings:read", "x-rate-limit-bucket": "reads", "summary": "One listing", "description": "Scope `listings:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1Listings", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listing" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Listings" ], "x-scope": "listings:write", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Change price, stock, status or anything else", "description": "Scope `listings:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "patchV1Listings", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 4, "maxLength": 120 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "min_qty": { "type": "integer", "minimum": 2, "maximum": 1000000 }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" } }, "required": [ "min_qty", "price" ], "additionalProperties": false }, "maxItems": 3 }, "description": { "type": "string", "maxLength": 2000 }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "USD" }, "unit_label": { "type": "string", "minLength": 1, "maxLength": 40, "default": "unit" }, "price_per_qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "min_qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "max_qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "nullable": true }, "stock_qty": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 0 }, "low_stock_alert_qty": { "type": "integer", "minimum": 0, "maximum": 10000000, "nullable": true }, "delivery_eta_minutes": { "type": "integer", "minimum": 1, "maximum": 20160, "default": 60 }, "attributes": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 80 } }, "external_id": { "type": "string", "minLength": 1, "maxLength": 120, "nullable": true }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "removed" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The listing, after the change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listing" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/listings/{id}/tiers": { "put": { "tags": [ "Listings" ], "x-scope": "listings:write", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Replace the volume ladder", "description": "Up to three rungs, each starting above the one before and cheaper than it; the listing's own price is the price at its minimum order. Checkout picks the rung an order's quantity reaches and freezes that unit price on the order. An empty list clears the ladder.\n\nScope `listings:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "putV1ListingsTiers", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tiers": { "type": "array", "items": { "type": "object", "properties": { "min_qty": { "type": "integer", "minimum": 2, "maximum": 1000000 }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" } }, "required": [ "min_qty", "price" ], "additionalProperties": false }, "maxItems": 3 } }, "required": [ "tiers" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The listing, with its ladder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Listing" } } } }, "400": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders": { "get": { "tags": [ "Orders" ], "x-scope": "orders:read", "x-rate-limit-bucket": "reads", "summary": "Your orders, or everything that moved since a moment", "description": "Without `updated_since`: newest change first. With it: a feed, oldest first, that you walk forward with the cursor.\n\nScope `orders:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1Orders", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "paid", "accepted", "delivering", "delivered", "completed", "disputed", "refunded", "partially_refunded", "cancelled", "expired" ] } }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "A page of orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass back as ?cursor= for the next page. Null on the last page." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/changes": { "get": { "tags": [ "Orders" ], "x-scope": "orders:read", "x-rate-limit-bucket": "reads", "x-conditional": true, "summary": "Has anything moved", "description": "Send back the ETag as If-None-Match. A 304 costs no database work, so poll at the pace in Poll-Interval with a clear conscience.\n\nScope `orders:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1OrdersChanges", "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The ETag from the previous answer. A match is a 304 with no body." } ], "responses": { "200": { "description": "Something moved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderChanges" } } } }, "304": { "description": "Nothing moved" }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/{id}": { "get": { "tags": [ "Orders" ], "x-scope": "orders:read", "x-rate-limit-bucket": "reads", "summary": "One order", "description": "Scope `orders:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1Orders", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/{id}/events": { "get": { "tags": [ "Orders" ], "x-scope": "orders:read", "x-rate-limit-bucket": "reads", "summary": "The order's timeline", "description": "Scope `orders:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1OrdersEvents", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderEvent" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/{id}/accept": { "post": { "tags": [ "Orders" ], "x-scope": "orders:write", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Take the order", "description": "Starts the delivery window from the listing's quoted time.\n\nScope `orders:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1OrdersAccept", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/{id}/deliver": { "post": { "tags": [ "Orders" ], "x-scope": "orders:write", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Mark delivered", "description": "Refused with `credentials_required` on an account order without a handover.\n\nScope `orders:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1OrdersDeliver", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "responses": { "200": { "description": "Delivered; the buyer's confirmation window has started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/{id}/decline": { "post": { "tags": [ "Orders" ], "x-scope": "orders:write", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Decline a paid order", "description": "The buyer is refunded in full.\n\nScope `orders:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1OrdersDecline", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "responses": { "200": { "description": "Refunded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/{id}/credentials": { "post": { "tags": [ "Orders" ], "x-scope": "orders:write", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "The account handover", "description": "Stored encrypted, readable by the buyer of this order alone. Never put a password in the chat.\n\nScope `orders:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1OrdersCredentials", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_username": { "type": "string", "minLength": 1, "maxLength": 128 }, "account_password": { "type": "string", "minLength": 1, "maxLength": 256 }, "email_username": { "type": "string", "minLength": 1, "maxLength": 128 }, "email_password": { "type": "string", "minLength": 1, "maxLength": 256 }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "account_username", "account_password" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/{id}/messages": { "get": { "tags": [ "Chat" ], "x-scope": "chat:read", "x-rate-limit-bucket": "reads", "summary": "The thread with the buyer", "description": "Scope `chat:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1OrdersMessages", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Chat" ], "x-scope": "chat:write", "x-rate-limit-bucket": "chat", "x-idempotent": true, "summary": "Send a message", "description": "The same contact detection as the site. Warnings come back to you; the message still goes.\n\nScope `chat:write`. Spends the `chat` budget (30 a minute for a new seller).", "operationId": "postV1OrdersMessages", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagePosted" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/listings/{id}/codes": { "get": { "tags": [ "Listings" ], "x-scope": "listings:read", "x-rate-limit-bucket": "reads", "summary": "The code vault, counted", "description": "How many codes a gift-card or top-up listing holds, by state. Never the codes themselves.\n\nScope `listings:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1ListingsCodes", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeVault" } } } }, "400": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Listings" ], "x-scope": "listings:write", "x-rate-limit-bucket": "bulk", "x-idempotent": true, "summary": "Stock codes", "description": "Up to a thousand a call, encrypted at rest. A code already in the vault is a duplicate and not stocked twice; one withdrawn earlier comes back. Stock rises by what was added. From then on an order on this listing is accepted and delivered the moment it is paid, with the codes attached for the buyer; a vault short of the order quantity leaves that order for you to deliver by hand.\n\nScope `listings:write`. Spends the `bulk` budget (20 a minute for a new seller).", "operationId": "postV1ListingsCodes", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string", "minLength": 4, "maxLength": 200 }, "minItems": 1, "maxItems": 1000 } }, "required": [ "codes" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "What landed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeVaultAdded" } } } }, "400": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/listings/{id}/codes/withdraw": { "post": { "tags": [ "Listings" ], "x-scope": "listings:write", "x-rate-limit-bucket": "writes", "summary": "Take unsold codes off the shelf", "description": "The codes named, or every unsold one when none are. Stock falls by the same count.\n\nScope `listings:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1ListingsCodesWithdraw", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string", "minLength": 4, "maxLength": 200 }, "minItems": 1, "maxItems": 1000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "What left", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeVaultWithdrawn" } } } }, "400": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/boost-templates": { "get": { "tags": [ "Boosting" ], "x-rate-limit-bucket": "reads", "summary": "The services a game standardises", "description": "Every boost template for one game, with the knobs a curve prices: a range or number option takes a per-unit rate, a choice option takes basis points per value, a flags option takes basis points per extra you offer. `offer_id` is your curve on it, if you have one.\n\nAny key. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1BoostTemplates", "parameters": [ { "name": "game", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "In the hub order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BoostTemplate" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/boost-offers": { "get": { "tags": [ "Boosting" ], "x-scope": "listings:read", "x-rate-limit-bucket": "reads", "summary": "Your curves", "description": "Scope `listings:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1BoostOffers", "parameters": [], "responses": { "200": { "description": "Every curve, across games", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BoostOffer" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/boost-offers/{template}": { "put": { "tags": [ "Boosting" ], "x-scope": "listings:write", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Publish or replace your curve on a template", "description": "One curve per template: a second call replaces it and sets it active. Every rate must name an option the template defines. The cheapest configuration the curve prices is the \"from\" price on the hub and must be above zero. Prices are decimal USD.\n\nScope `listings:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "putV1BoostOffers", "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pricing": { "type": "object", "properties": { "base": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, "per_unit": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" } }, "choice_bps": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "minimum": -9000, "maximum": 40000 } } }, "flag_bps": { "type": "object", "additionalProperties": { "type": "integer", "minimum": -9000, "maximum": 40000 } }, "min_total": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" } }, "required": [ "base" ], "additionalProperties": false }, "eta_hours": { "type": "integer", "minimum": 1, "maximum": 336 } }, "required": [ "pricing", "eta_hours" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The offer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoostOffer" } } } }, "400": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/boost-offers/{id}": { "patch": { "tags": [ "Boosting" ], "x-scope": "listings:write", "x-rate-limit-bucket": "writes", "summary": "Pause or resume a curve", "description": "Pausing is always allowed. Resuming is starting to sell again, which a suspended account cannot do.\n\nScope `listings:write`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "patchV1BoostOffers", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The offer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoostOffer" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/stock/syncs": { "get": { "tags": [ "Stock syncs" ], "x-scope": "listings:read", "x-rate-limit-bucket": "reads", "summary": "Your last fifty syncs", "description": "Scope `listings:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1StockSyncs", "parameters": [], "responses": { "200": { "description": "Newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StockSync" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Stock syncs" ], "x-scope": "listings:write", "x-rate-limit-bucket": "bulk", "summary": "Open a sync", "description": "Replace mode pauses every listing with an external id the sync does not mention; merge mode touches only the lines sent. An open sync expires after an hour.\n\nScope `listings:write`. Spends the `bulk` budget (20 a minute for a new seller).", "operationId": "postV1StockSyncs", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "replace", "merge" ], "default": "merge" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Open", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockSync" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/stock/syncs/{id}": { "get": { "tags": [ "Stock syncs" ], "x-scope": "listings:read", "x-rate-limit-bucket": "reads", "summary": "One sync, with its summary once committed", "description": "Scope `listings:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1StockSyncs", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockSync" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/stock/syncs/{id}/lines": { "put": { "tags": [ "Stock syncs" ], "x-scope": "listings:write", "x-rate-limit-bucket": "bulk", "summary": "Stage up to a thousand lines", "description": "Each line is validated on its own and its game, category, server and package resolved; a bad line is reported here and counted as failed at commit, and the rest go on. The same external id staged again keeps the later line.\n\nScope `listings:write`. Spends the `bulk` budget (20 a minute for a new seller).", "operationId": "putV1StockSyncsLines", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "game": { "type": "string", "minLength": 1, "maxLength": 64 }, "category": { "type": "string", "minLength": 1, "maxLength": 64 }, "server": { "type": "string", "minLength": 1, "maxLength": 64 }, "package": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string", "minLength": 4, "maxLength": 120 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "min_qty": { "type": "integer", "minimum": 2, "maximum": 1000000 }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" } }, "required": [ "min_qty", "price" ], "additionalProperties": false }, "maxItems": 3 }, "description": { "type": "string", "maxLength": 2000 }, "price": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "USD" }, "unit_label": { "type": "string", "minLength": 1, "maxLength": 40, "default": "unit" }, "price_per_qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "min_qty": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "max_qty": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "stock_qty": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 0 }, "low_stock_alert_qty": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "delivery_eta_minutes": { "type": "integer", "minimum": 1, "maximum": 20160, "default": 60 }, "attributes": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 80 } }, "external_id": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "draft", "active", "paused" ], "default": "active" } }, "required": [ "game", "category", "price", "external_id" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 } }, "required": [ "lines" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "A result per line", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Staged" } } } }, "400": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Stock syncs" ], "x-scope": "listings:read", "x-rate-limit-bucket": "reads", "summary": "The lines, with the result each got", "description": "Scope `listings:read`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1StockSyncsLines", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "created", "updated", "unchanged", "paused", "failed" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } } ], "responses": { "200": { "description": "In staging order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SyncLine" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass back as ?cursor= for the next page. Null on the last page." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/stock/syncs/{id}/commit": { "post": { "tags": [ "Stock syncs" ], "x-scope": "listings:write", "x-rate-limit-bucket": "bulk", "summary": "Apply the sync", "description": "Returns at once; the worker applies it in short transactions, recounts your catalog pages once, and stamps a result on every line.\n\nScope `listings:write`. Spends the `bulk` budget (20 a minute for a new seller).", "operationId": "postV1StockSyncsCommit", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Committing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockSync" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "x-scope": "webhooks:manage", "x-rate-limit-bucket": "reads", "summary": "Your endpoints", "description": "Scope `webhooks:manage`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1Webhooks", "parameters": [], "responses": { "200": { "description": "Every endpoint, never a secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "x-scope": "webhooks:manage", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Add an endpoint", "description": "HTTPS only, to a public address. Up to five per account. An empty `events` list subscribes to everything. The secret is in this one response and nowhere else.\n\nScope `webhooks:manage`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1Webhooks", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 32, "default": [] }, "label": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created, with the secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" } } } }, "400": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "x-scope": "webhooks:manage", "x-rate-limit-bucket": "reads", "summary": "One endpoint", "description": "Scope `webhooks:manage`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1Webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Webhooks" ], "x-scope": "webhooks:manage", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "Change the URL, the events, the label, or re-enable it", "description": "Scope `webhooks:manage`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "patchV1Webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 2048 }, "events": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 32, "default": [] }, "label": { "type": "string", "minLength": 1, "maxLength": 60, "nullable": true }, "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The endpoint, after the change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Webhooks" ], "x-scope": "webhooks:manage", "x-rate-limit-bucket": "writes", "summary": "Remove an endpoint and its delivery log", "description": "Scope `webhooks:manage`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "deleteV1Webhooks", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Gone" }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "x-scope": "webhooks:manage", "x-rate-limit-bucket": "writes", "summary": "Send a ping through the real pipeline", "description": "Scope `webhooks:manage`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1WebhooksTest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Queued; it arrives within a few seconds and shows in the delivery log", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Queued" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "x-scope": "webhooks:manage", "x-rate-limit-bucket": "writes", "x-idempotent": true, "summary": "New secret, with a day of overlap", "description": "Deliveries carry two signatures for 24 hours, one with each secret, so the receiver can be switched over without a gap.\n\nScope `webhooks:manage`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1WebhooksRotateSecret", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Any string you choose, up to 200 characters. A repeat within a day gets the first response back with `Idempotent-Replayed: true`." } ], "responses": { "200": { "description": "The endpoint, with the new secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookWithSecret" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "x-scope": "webhooks:manage", "x-rate-limit-bucket": "reads", "summary": "The delivery log", "description": "Scope `webhooks:manage`. Spends the `reads` budget (600 a minute for a new seller).", "operationId": "getV1WebhooksDeliveries", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed", "exhausted" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass back as ?cursor= for the next page. Null on the last page." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries/{deliveryId}/replay": { "post": { "tags": [ "Webhooks" ], "x-scope": "webhooks:manage", "x-rate-limit-bucket": "writes", "summary": "Send a delivery again, now", "description": "Scope `webhooks:manage`. Spends the `writes` budget (120 a minute for a new seller).", "operationId": "postV1WebhooksDeliveriesReplay", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Queued as a fresh attempt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } } }, "401": { "description": "No key, or a key that is not live here", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The budget for the minute is spent; wait for Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "x-scopes": [ "catalog:read", "listings:read", "listings:write", "orders:read", "orders:write", "chat:read", "chat:write", "account:read", "account:write", "webhooks:manage" ], "x-rate-limits": { "reads": { "limit": 600, "windowMs": 60000 }, "writes": { "limit": 120, "windowMs": 60000 }, "bulk": { "limit": 20, "windowMs": 60000 }, "chat": { "limit": 30, "windowMs": 60000 } }, "x-webhooks": { "events": [ "order.paid", "order.accepted", "order.delivering", "order.delivered", "order.completed", "order.cancelled", "order.refunded", "order.expired", "order.disputed", "order.dispute_resolved", "order.message", "listing.low_stock", "listing.sold_out", "listing.taken_down", "listing.reinstated", "account.trading_status_changed", "ping" ], "body": { "$ref": "#/components/schemas/WebhookEvent" }, "headers": { "Freeport-Signature": "t=,v1=[,v1=]", "Freeport-Event-Id": "The event id; the same event never arrives with another.", "Freeport-Event-Type": "The event type.", "Freeport-Delivery-Id": "This attempt's delivery id, for the log." }, "signature": "HMAC-SHA256 with your endpoint secret over `${t}.${body}` where body is the raw bytes. Accept a delivery if any v1 matches. Refuse a t more than five minutes from now.", "retries_seconds": [ 60, 300, 1800, 7200, 21600, 43200, 86400, 86400, 86400 ], "max_attempts": 10, "disabled_after_hours": 72, "ordering": "Not guaranteed across events. Every order event carries seq; fetch the order on receipt rather than trusting the body's state.", "timeout_seconds": 10, "redirects": "Never followed; a 3xx is a failed attempt." }, "x-request-signing": { "opt_in": "Turn signing on for a key from Selling, then Integrations. You get a signing secret once.", "headers": { "Freeport-Timestamp": ", within five minutes of now", "Freeport-Signature": "v1=" }, "signature": "HMAC-SHA256 with the signing secret over `${timestamp}.${METHOD}.${request-target}.${sha256hex(body)}`; the request-target is the path and query exactly as sent, and the body is the raw bytes or empty.", "replay": "A signature is accepted once inside its window." } }