Migrating Sales Data to v1

The sales data endpoints now have v1 equivalents:

Both versions are live. The v0.3 endpoints are not deprecated and remain fully supported — v1 is the modern contract, not a forced cutover. v1 returns the same sales rows plus a listing_id on every row, and adds cursor pagination, a JSON response envelope, structured JSON errors, and an optional source filter for selecting which marketplace a row was observed on.

Authentication — nothing to migrate

Same 64-character key, same headers. Authorization: Bearer <key> is preferred; the legacy api-key: <key> header also works on every endpoint.

Single-event sales: GET /v1/events/{event_id}/sales

What changed from GET /v0.3/salesdata/get:

Requests

GET /api/v1/events/12345/sales?limit=200 HTTP/1.1
Authorization: Bearer <your-64-character-key>

Marketplace Event ID instead of SeatData Event ID:

GET /api/v1/events/98765/sales?id_type=marketplace HTTP/1.1
Authorization: Bearer <your-64-character-key>

Next page:

GET /api/v1/events/12345/sales?starting_after=<next_cursor> HTTP/1.1
Authorization: Bearer <your-64-character-key>

Success shape

{
  "event_id": 12345,
  "data": [
    { "timestamp": 1789489812, "quantity": 2, "price": 145.0,
      "zone": "Lower Level", "section": "112", "row": "12",
      "listing_id": 4871203955, "source": "sh", "all_in_price": null },
    { "timestamp": 1789489140, "quantity": 2, "price": 139.0,
      "zone": "", "section": "Lower Level 112", "row": "14",
      "listing_id": "8815520431", "source": "vs", "all_in_price": 171.5,
      "norm_zone": "Lower Level", "norm_section": "112" }
  ],
  "has_more": true,
  "next_cursor": "opaque-token-string",
  "total_count": 42,
  "sources": [
    { "source": "sh", "collecting_since": "2026-01-15", "tracked_for_event": true, "status": "ok" },
    { "source": "vs", "collecting_since": "2026-08-30", "tracked_for_event": true, "status": "ok" }
  ]
}

• total_count appears on the first page only (omitted on continuation pages), and counts rows under the active source filter.
• sources appears on the first page only. It always carries two entries, sh first, whatever source you sent. status: "unavailable" means that marketplace could not be read for this request; the response still succeeds with the rows that were available.
• collecting_since reports the earliest sale observed for that event on that marketplace, counting sales these endpoints do not return. You can see a collecting_since older than your oldest returned row.
• next_cursor is opaque — pass it back verbatim, don't parse it. It's scoped to that one event and the source it was issued under; a cursor from another event, endpoint, or source returns 400 invalid_cursor. Cursors expire after 1 hour (same as the stats endpoint).
• event_id echoes the literal value from the path.

Each row is a real sale transaction. Sales whose seat details could not be determined are not returned, and are not counted in total_count.

Multi-source rows

The source parameter is optional and defaults to sh. A request that omits it returns exactly what it returned before, at the same cost, so no existing integration needs to change.

Every row carries source and all_in_price:

A vs row carries two more:

sh rows carry neither. Their names are the naming space vs rows are translated into, so they have nothing to translate.

Joining the two sources

The normalized fields exist so you can line a vs sale up against the sh sales for the same seats. Compare norm_section against section, and norm_zone against zone:

primary   = [r for r in rows if r["source"] == "sh"]
secondary = [r for r in rows if r["source"] == "vs"]

for sale in secondary:
    same_seats = [
        r for r in primary
        if r["section"] == sale["norm_section"]
        and r["zone"] == sale["norm_zone"]
    ]

An empty norm_section or norm_zone means no match was found; those rows cannot be joined this way.

Quantity and price

sh sales often reach us unenriched, without a quantity or price. For those we derive both from the listing data we hold for that listing; a quantity of 0 means it could not be reliably determined. vs sales carry both as reported.

Batch sales: POST /v1/events/sales/batch

What changed from POST /v0.3/salesdata/batch:

• results/errors are keyed by the exact identifier string you sent (a SeatData ID and a Marketplace ID that resolve to the same event are echoed under both keys).
• Batch has no pagination and no id_type parameter — it returns all rows per event, driven by the two-list body. Only the single-event GET paginates.
• source is a query-string parameter here, not a body field: POST /api/v1/events/sales/batch?source=all.
• The response adds a top-level sources object keyed by the same client-sent event ids as results. Each value lists both marketplaces, sh first, whatever source you sent. results and errors are unchanged in shape.
• Billing is per-event: each event that returns rows is charged once; empty events are free. If the balance runs out mid-batch, already-affordable events are still served and the rest come back as "payment_required" in errors; if nothing is affordable, the endpoint returns 402. Identical to v0.3.

Error envelope (both v1 endpoints)

v0.3 returned plain-text errors and collapsed most failures into generic 400/401 responses. v1 returns a structured envelope so clients can branch on the specific failure:

{ "error": { "type": "...", "code": "...", "message": "...", "param": "..." } }

param appears only for input-validation errors. Codes these endpoints emit:

Two shapes to be aware of:

• A non-integer event id in the GET path never reaches the API — URL routing rejects it with a plain HTTP 404 page, not a JSON envelope. Any integer id that doesn't match an event returns 404 event_not_found as JSON.
• The 402 body is a flat balance envelope, not the nested error object above: {"error": "payment_required", "code": "...", ...} with balance details and a top_up_url for adding funds.

For current rate limits, treat GET /v1/account and the rate-limit response headers as authoritative — see the Rate Limits guide.