Deleted Items

When a record leaves the catalog, your delta sync sees a compact tombstone row on the same dateModifiedFrom loop — one watermark covers both updates and removals.

What a tombstone is

A tombstone is the same envelope as a normal feed row, stripped down to the bare identifying fields plus a removal marker. It tells a long-lived mirror that an identifier it cached has left the catalog — hard-deleted, soft-deleted (“trashed”), or merged into another record — so you can drop or redirect the row. Removals ride the same delta loop you already run for updates: there is no second endpoint and no second watermark.

Do not confuse the two status families: eventStatus describes the schedule of a live event, while deletionStatus appears only on a tombstone after a record has left the catalog.

When they appear

Only on delta polls — never on catalog browsing.

The removals object

A dateModifiedFrom response also carries a top-level removals object that says which removal rows the response covers.

FieldMeaning
availableFromThe oldest sync point for which removal rows are still kept.
completetrue when the response can include every removal since your dateModifiedFrom.
scopeall: every removal in the window. matched: only the removals that match your filter. none: this request carries no removal rows.

When complete is false, your sync point is older than availableFrom, so some removals may be missing. Deleted and trashed rows are kept for 90 days; merges are kept for ever. Re-check your cached identifiers with a lookup by ID or rebuild your cache.

eventStatus values

The scheduling state of a live event. Keep the row and update its presentation.

ValueMeaningRecommended handling
scheduledThe event is expected to happen at its current start date.Show it normally.
postponedThe event is delayed and a replacement date is not yet confirmed.Keep it, label it postponed, and avoid promising the current date.
rescheduledThe event has moved to a confirmed new date. previousStartDate may contain the prior date.Keep it and update users from the old date to the new one.
cancelledThe event will not take place as scheduled, but it remains a live catalog row.Keep it for history and joins; hide it or clearly label it in upcoming views.

All four values arrive on normal rows and can change in later delta polls. Always persist eventStatus on upsert. None of these values is a tombstone discriminator.

deletionStatus values

A single discriminator carries the removal class. Live rows omit the field entirely.

ValueMeaningExtra fieldsWhat to do
deletedHard-deleted upstream. The identifier is gone and will not be re-used.deletedAtDrop the row from your cache.
trashedSoft-deleted upstream. This class is emitted for events only and is not an eventStatus value.deletedAtTreat the same as deleted and drop it. A restored show keeps arriving as a removal row until it is back in the catalog, then returns as a normal live row.
mergedFolded into another record. This row’s identifier is the loser; mergedInto is the survivor.deletedAt, mergedIntoRepoint cached references to mergedInto.

mergedInto is the next-hop survivor only. If a survivor later merges again, that produces another tombstone pointing at the next survivor — walk merges as they arrive across delta windows.

Wire shape

A single delta page can mix live rows and tombstones.

A page from GET /v3/events?dateModifiedFrom=2026-04-12T00:00:00Z can include live rows and any supported tombstone class together. Tombstone rows carry only @type, identifier, deletionStatus, deletedAt, dateModified, and (on merged) mergedInto — everything else is omitted.

{
"success": { "code": 200 },
"pagination": {
"page": 1, "perPage": 40, "totalItems": 4, "totalPages": 1,
"nextPage": null, "previousPage": null
},
"events": [
{
"@type": "Concert",
"identifier": "jambase:16100021",
"name": "Phish at Madison Square Garden",
"eventStatus": "scheduled",
"dateModified": "2026-04-12T17:34:00Z"
},
{
"@type": "Concert",
"identifier": "jambase:16223890",
"deletionStatus": "trashed",
"deletedAt": "2026-08-19T18:01:00Z",
"dateModified": "2026-08-22T14:25:00Z"
},
{
"@type": "Concert",
"identifier": "jambase:16223891",
"deletionStatus": "deleted",
"deletedAt": "2026-04-12T18:01:00Z",
"dateModified": "2026-04-12T18:01:00Z"
},
{
"@type": "Concert",
"identifier": "jambase:15479255",
"deletionStatus": "merged",
"deletedAt": "2026-04-12T19:22:00Z",
"mergedInto": "jambase:5632389",
"dateModified": "2026-04-12T19:22:00Z"
}
]
}

Handling tombstones

Branch on deletionStatus inside your existing upsert loop.

Because tombstones arrive on the same response as live rows, you handle them on the same code path — just switch on deletionStatus before upserting:

for (const row of response.events) {
switch (row.deletionStatus) {
case "deleted":
case "trashed":
db.events.delete(row.identifier); // drop from your cache
break;
case "merged":
db.events.repoint(row.identifier, row.mergedInto); // redirect references
break;
default:
db.events.upsert(row.identifier, row); // live row — normal upsert
}
}

Per-feed coverage

Current source coverage, not hypothetical schema capability.

Feed@typeCurrently sourced deletionStatus values
/v3/eventsConcert, Festivaldeleted, trashed, merged
/v3/artistsMusicGroupdeleted, merged
/v3/venuesVenuedeleted, merged
/v3/streamsStreamNone. Stream tombstones are not currently sourced or emitted.

Festival removals arrive on /v3/events with @type Festival, next to concert removals. /v3/festivals and the festival series routes carry no removal rows. Venue removal rows say Venue, the same type as live venue rows (they used to say MusicVenue), and so do venue locations on festival series editions. Other venue objects, such as event locations, use the same value, so you can handle venue objects the same way whether they are live or removed. /v3/streams currently emits no tombstones. Look up previously cached streams by ID instead (a removed stream answers 400 identifier_invalid).

Pagination & retention

Tombstones page like any other row, and the window is bounded.

  • They count toward paging. Tombstones count against perPage and pagination.totalItems in one combined total, after the live rows. A perPage=100 page may be any mix of live rows and tombstones. Artist- and venue-filtered deltas count only the tombstones that match the filter.
  • Retention is 90 days. deleted and trashed tombstones are kept for 90 days, then disappear from the feed. merged tombstones never expire, because merge collisions in a long-running cache are worse than a stale delete. This window applies to the delta feeds only; a lookup by ID has no time limit.
  • Two timestamps. dateModified is when the removal became visible on the feed, the value your watermark matches. deletedAt is the true removal time in UTC and can be earlier.
  • No historical-access tier needed. Tombstones ride the standard dateModifiedFrom loop and reveal only that an identifier left the catalog. Subscriptions limited to upcoming events get them too. On /v3/events their removal rows cover shows dated today or later, so a removed show with an earlier date does not appear. Their artist and venue removal rows are not limited by date.

Looking up a removed record

Check one cached identifier at a time, with or without tombstones.

Look up a stored JamBase ID with GET /v3/events/id/jambase:{id} (or the matching artists or venues lookup). If the record was removed, the response is 200 with its removal row in place of the record, for example { "success": true, "event": { "identifier": "jambase:123", "deletionStatus": "deleted", ... } }. The row has the same fields as a tombstone on the feed. Check for deletionStatus before you treat a lookup result as a live record: drop the cached row for deleted or trashed, and repoint it to mergedInto for merged.

Lookups have no time limit. A deleted or trashed record answers with its removal row however long ago it was removed, just as a merged record does. The 90-day window applies to the delta feeds, not to lookups. Subscriptions limited to upcoming events get the same answer.

The lookup answers 400 with error code identifier_invalid instead for lookups by another source's ID (for example a Ticketmaster ID) and for stream lookups. Treat that answer on a previously cached identifier as removed.

If removal rows cannot be read, the delta request fails, normally with HTTP 503, error code removals_unavailable and a Retry-After header. You never get live rows without their removal rows.

Wait as long as Retry-After says, then retry the same page with the same dateModifiedFrom. Do not advance your watermark past a failed page.

Related

Last updated Nov 16, 2026