{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/soldgraph-com/json-schema/soldgraph-com-ebay-sold-job-schema.json",
  "title": "EbaySoldJob",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/soldgraph-com-ebay-api-openapi.yml#/components/schemas/EbaySoldJob",
  "type": "object",
  "required": [
    "request_id",
    "status",
    "credits",
    "cached"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "description": "ID of this request. Poll it at /v1/jobs/{request_id}."
    },
    "status": {
      "type": "string",
      "description": "pending, complete or failed. Always check it, even on HTTP 200.",
      "enum": [
        "pending",
        "complete",
        "failed"
      ]
    },
    "credits": {
      "type": "integer",
      "description": "Requests charged: 1 when complete, 0 for a page past the last one, while pending, or when failed."
    },
    "cached": {
      "type": "boolean",
      "description": "True when the result came from the 15-minute cache."
    },
    "poll_url": {
      "type": "string",
      "description": "Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL."
    },
    "result": {
      "$ref": "#/$defs/EbaySoldPage"
    },
    "error": {
      "type": "object",
      "required": [
        "code"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "page_mismatch",
            "schema",
            "network",
            "upstream",
            "throttled",
            "blocked",
            "rejected",
            "not_found",
            "filter_not_supported",
            "filter_not_applied",
            "location_not_served",
            "auth",
            "daily_limit",
            "deadline_exceeded",
            "credential_storage"
          ],
          "description": "Failed job code."
        },
        "message": {
          "type": "string",
          "description": "What the code means, in plain words."
        }
      }
    }
  },
  "$defs": {
    "EbaySoldPage": {
      "type": "object",
      "required": [
        "provider",
        "country",
        "query",
        "page",
        "count",
        "reported_total",
        "next_page",
        "collected_at",
        "schema_version",
        "completeness",
        "field_notes",
        "next_cursor",
        "page_size",
        "summary",
        "data"
      ],
      "properties": {
        "provider": {
          "type": "string",
          "description": "Marketplace ID, like ebay or poshmark."
        },
        "country": {
          "type": "string",
          "description": "The country searched: us, or on eBay the country you sent."
        },
        "query": {
          "type": "string",
          "description": "The q you sent, with extra spaces removed."
        },
        "page": {
          "type": "integer",
          "description": "The page you asked for."
        },
        "count": {
          "type": "integer",
          "description": "Rows in result.data on this page."
        },
        "reported_total": {
          "type": "integer",
          "description": "Total matches the marketplace reports for the search. It may be rounded or capped."
        },
        "next_page": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Send this as page to get the next page. Null on the last page, and on page 100, the deepest page served."
        },
        "collected_at": {
          "type": "string",
          "description": "When we collected the page, as an ISO 8601 timestamp."
        },
        "schema_version": {
          "type": "integer",
          "description": "Version of the result's shape for that marketplace: 1 or 2. It only rises when a field changes meaning."
        },
        "completeness": {
          "type": "string",
          "description": "provider_page_only: one page as the marketplace served it, not a full history. TCGplayer recent sales say recent_sample_only."
        },
        "field_notes": {
          "type": "string",
          "description": "Plain-text notes on how to read this page's fields."
        },
        "next_cursor": {
          "type": "null",
          "description": "Always null. eBay pages by number: send page=next_page for the next page."
        },
        "page_size": {
          "type": "integer",
          "description": "Rows per page, as eBay reports it."
        },
        "summary": {
          "type": "object",
          "properties": {
            "priced_count": {
              "type": "integer",
              "description": "Rows on this page that show one price in the site's currency."
            },
            "currency": {
              "type": "string",
              "description": "Currency of the amounts below."
            },
            "median": {
              "type": [
                "number",
                "null"
              ],
              "description": "Middle displayed price of those rows."
            },
            "low": {
              "type": [
                "number",
                "null"
              ],
              "description": "Lowest displayed price."
            },
            "high": {
              "type": [
                "number",
                "null"
              ],
              "description": "Highest displayed price."
            },
            "earliest_sold_date": {
              "type": [
                "string",
                "null"
              ],
              "description": "Oldest sold date on this page."
            },
            "latest_sold_date": {
              "type": [
                "string",
                "null"
              ],
              "description": "Newest sold date on this page."
            },
            "best_offer_accepted_count": {
              "type": "integer",
              "description": "Rows that sold by accepted Best Offer. eBay shows only the asking price on these, so they are kept out of `median_excluding_best_offer`."
            },
            "p25": {
              "type": [
                "number",
                "null"
              ],
              "description": "First-quartile displayed price: a quarter of priced rows are at or below it."
            },
            "p75": {
              "type": [
                "number",
                "null"
              ],
              "description": "Third-quartile displayed price. With `p25`, a range that ignores a stray accessory or parts listing."
            },
            "median_excluding_best_offer": {
              "type": [
                "number",
                "null"
              ],
              "description": "Median over rows whose displayed price is the sale price: accepted Best Offers, where eBay shows only the asking price, are left out. Null when every priced row was a Best Offer."
            }
          },
          "required": [
            "priced_count",
            "currency",
            "median",
            "low",
            "high",
            "earliest_sold_date",
            "latest_sold_date",
            "best_offer_accepted_count",
            "p25",
            "p75",
            "median_excluding_best_offer"
          ],
          "description": "Price maths over the rows on this page: priced_count, currency, median, low, high, p25, p75, earliest_sold_date, latest_sold_date and best_offer_accepted_count. No row is removed from data. Rows with a price range or an unread price are left out of the maths."
        },
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EbaySoldRow"
          }
        }
      }
    },
    "EbaySoldRow": {
      "type": "object",
      "required": [
        "id",
        "title",
        "link",
        "format",
        "displayed_price",
        "displayed_price_text",
        "displayed_price_range",
        "best_offer_accepted",
        "displayed_shipping",
        "shipping_text",
        "sold_date",
        "sold_date_text",
        "condition",
        "bid_count",
        "seller_text",
        "location_text",
        "image"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The marketplace's listing ID."
        },
        "title": {
          "type": [
            "string",
            "null"
          ],
          "description": "Listing title as shown."
        },
        "link": {
          "type": "string",
          "description": "URL of the listing on the eBay site you searched, like https://www.ebay.co.uk/itm/…."
        },
        "format": {
          "type": "string",
          "description": "auction when the sale had bids, otherwise fixed_price."
        },
        "displayed_price": {
          "oneOf": [
            {
              "$ref": "#/$defs/Money"
            },
            {
              "type": "null"
            }
          ],
          "description": "{ amount, currency } parsed from the price shown. Null if it couldn't be read. Null when eBay shows a price range for a multi-variation listing (\"$247.00 to $911.00\"): the amount wouldn't say which variant. The range is in displayed_price_range and displayed_price_text. When best_offer_accepted is true, this is the asking price, not the sale price."
        },
        "displayed_price_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "The price text as shown, like $189.00, £124.46 or €230.00."
        },
        "displayed_price_range": {
          "type": [
            "object",
            "null"
          ],
          "required": [
            "low",
            "high",
            "currency"
          ],
          "properties": {
            "low": {
              "type": "number"
            },
            "high": {
              "type": "number"
            },
            "currency": {
              "type": "string",
              "description": "ISO 4217 code, like USD."
            }
          },
          "description": "{ low, high, currency } when eBay shows a price range for a multi-variation listing (\"$247.00 to $911.00\"). Null otherwise. displayed_price is null for these rows, so they stay out of the summary maths."
        },
        "best_offer_accepted": {
          "type": "boolean",
          "description": "True when the sale closed on an accepted Best Offer. eBay does not publish the accepted amount on sold listings, so on these rows displayed_price is the seller's asking price. summary.median_excluding_best_offer gives the median of the rows whose price is the sale price."
        },
        "displayed_shipping": {
          "oneOf": [
            {
              "$ref": "#/$defs/Money"
            },
            {
              "type": "null"
            }
          ],
          "description": "{ amount, currency } read from exact shipping text, in the site's currency, like +$9.99 delivery, +£3.92 delivery or +€6.99 Lieferung. Free shipping is 0, in every country's wording. Estimates and Shipping not specified are null."
        },
        "shipping_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "Shipping text as shown, like +$9.99 delivery, Free delivery or + €10.49 de envío."
        },
        "sold_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "Sale date as YYYY-MM-DD. eBay's text has no year, so we use the most recent date that matches. Null if the text couldn't be read."
        },
        "sold_date_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "Sold date text as shown. eBay leaves out the year. The order depends on the site: Sep-21 14:35 (US, Australia, France, Italy, Spain), 21-Sep 14:35 (UK, Canada) or 21. Sep. 14:35 (Germany)."
        },
        "condition": {
          "type": [
            "string",
            "null"
          ],
          "description": "eBay's condition text as shown, in the site's language, like Pre-Owned, Pre-owned or Gebraucht. To filter by condition in any language, use condition."
        },
        "bid_count": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Number of bids, for auctions. Null for fixed-price sales."
        },
        "seller_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "Seller text as eBay shows it: username, feedback count and positive percentage, e.g. clutch_supply (1,325) 99.7%."
        },
        "location_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "Seller location text as eBay shows it, like Located in United States or da Germania. Often null for sellers in the country you searched."
        },
        "image": {
          "type": [
            "string",
            "null"
          ],
          "description": "Image URL on i.ebayimg.com."
        }
      }
    },
    "Money": {
      "type": "object",
      "required": [
        "amount",
        "currency"
      ],
      "properties": {
        "amount": {
          "type": "number"
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217 code, like USD."
        }
      }
    }
  }
}