Sales channels

Channels are allocation labels on an event’s inventory. Read sales channels first for the model; this page is the wire reference.

Two capabilities gate everything here, and neither implies the other:

event:block grants neither. Manage tokens minted before channels existed keep exactly the capabilities they had.

List channels

Add ?includeArchived=1 to include archived channels.

{
  "assignmentVersion": 1,
  "publicSale": {
    "id": "public",
    "name": "Public sale",
    "state": "active",
    "counts": { "allocated": 5, "free": 5, "held": 0, "booked": 0, "blocked": 0, "units": 5 }
  },
  "channels": [
    {
      "id": "chn_9f1c", "name": "Travel Agency A",
      "color": "#7C5CFF", "marker": "diagonal", "externalRef": "ta-a",
      "state": "active", "archiveDestination": null, "accessIntent": "none",
      "createdAt": 1764600000000, "updatedAt": 1764600000000, "archivedAt": null,
      "counts": { "allocated": 3, "free": 3, "held": 0, "booked": 0, "blocked": 0, "units": 3 },
      "access": { "intent": "none", "hasActiveGrants": false, "lastMintAt": null }
    }
  ]
}

counts are guest-weighted, so a grouped table contributes its guests; units is the number of inventory rows behind them. allocated is free + held + booked + blocked.

state is active, paused, or archived.

The access object

accessIntent is what you declared; the two derived fields are read from the grant store, so a row can distinguish “server integration configured” from “server integration declared, nothing ever minted”.

accessIntent grants nothing. What a caller may select is derived from the credential presented, never from this field.

Create a channel

Returns 201 {"ok": true, "channel": {…}} with zeroed counts. Creating a channel does not move assignmentVersion — no inventory changed hands.

Public sale and public are reserved names and return 409 channel_name_taken.

Rename, or change the declared access method

Send name, accessIntent, or both. Sending neither returns 422 channel_name_required. Returns {"ok": true, "channel": {…}} with the bare record — no counts, no access sub-object.

Neither operation moves assignmentVersion.

Apply an allocation

This is the operation worth reading carefully. It is versioned, non-destructive, and reports exactly what it did.

{
  "targetChannelId": "chn_9f1c",
  "labels": ["A-1", "A-2", "A-3"],
  "assignmentVersion": 1
}

assignmentVersion is concurrency control

assignmentVersion is a counter that moves only when an assignment lands — an Apply that changed something, or an archive. A busy on-sale moves the event’s updatedAt constantly and never touches this, so your operator’s staged edit does not go stale just because tickets are selling.

Send the version you read. If someone else changed the allocation in between, nothing moves and you get:

{
  "error": "channel_assignment_conflict",
  "code": "channel_assignment_conflict",
  "message": "The channel allocation changed after it was read; refresh and review",
  "details": { "assignmentVersion": 2, "expectedAssignmentVersion": 1 }
}

409. details.assignmentVersion is the server’s current value — re-read, show your operator what changed, and retry. Do not retry automatically with the returned version: that turns a safety mechanism into a silent overwrite of a colleague’s work.

The six buckets

{
  "ok": true,
  "targetChannelId": "chn_9f1c",
  "assignmentVersion": 2,
  "requested": 6,
  "applied": 3,
  "buckets": {
    "changedFromPublic":     { "count": 2 },
    "movedFromOtherChannel": {
      "count": 1,
      "channels": [ { "channelId": "chn_4a7b", "name": "Sponsor guests", "count": 1 } ]
    },
    "alreadyInTarget": { "count": 1 },
    "skippedHeld":     { "count": 1, "labels": ["A-7"], "truncated": false },
    "skippedBooked":   { "count": 0, "labels": [], "truncated": false },
    "notFound":        { "count": 1, "labels": ["ZZ-9"], "truncated": false }
  }
}

Every requested label lands in exactly one bucket.

• requested counts labels after de-duplication.
• applied = changedFromPublic.count + movedFromOtherChannel.count. Only free and blocked inventory is ever written.
• Seats in someone’s checkout and seats already sold are never moved. That is the non-destructive guarantee, and it is why an Apply is safe on a live event.
• movedFromOtherChannel.channels[].name is null when the source channel row is gone.
• The three sampled buckets list at most 50 labels; truncated: true means the count exceeded the sample.
• When applied is 0, assignmentVersion comes back unchanged — an all-skipped Apply does not invalidate the version you are holding.

422 too_many_units carries details: {requested, maximum} when a request exceeds 5,000 units.

Read the allocation map

Label to channel, paged by label. Carries no hold, booking, price, or buyer data.

{
  "assignmentVersion": 1,
  "allocations": [
    { "label": "A-1", "channelId": "chn_9f1c" },
    { "label": "A-4", "channelId": "public" }
  ],
  "nextAfterLabel": "A-4"
}

nextAfterLabel is null on the last page.

Preview an audience

Returns the seat projection a buyer with that exact scope would receive — the same code path a real buyer session uses, not an approximation. Read-only, and it mints nothing.

{
  "ok": true,
  "audience": { "channelIds": ["chn_9f1c"], "includePublic": false },
  "available": true,
  "seats": { "A-1": "free", "A-3": "blocked" },
  "hidden": [], "closed": [],
  "updatedAt": 1764600000000,
  "assignmentVersion": 1
}

A paused, archived, or unknown channel answers with the real unavailable landing state rather than its seats — still 200:

{
  "ok": true,
  "audience": { "channelIds": ["chn_ghost"], "includePublic": false },
  "available": false,
  "unavailable": [ { "channelId": "chn_ghost", "state": "not_found" } ],
  "assignmentVersion": 1
}

Naming more than 20 channels, or an empty scope, returns 422 invalid_channel_scope.

Use this before a partner goes live: it is the check that the allocation you applied is the inventory the partner will actually see.

Pause and resume

Pausing stops new access and new holds. Existing holds run to their normal expiry — pausing never strands a buyer mid-checkout. Optional reason is recorded. Returns {"ok": true, "channel": {…}}.

Neither moves assignmentVersion.

Archive with a destination

Archiving closes a channel for good and says where its inventory goes.

Archive takes no assignmentVersion. It is unconditional and returns the new value.

{
  "ok": true,
  "channel": {
    "id": "chn_9f1c", "name": "Travel Agency A", "state": "archived",
    "archiveDestination": "public", "archivedAt": 1764600001000
  },
  "assignmentVersion": 2,
  "moved": { "free": 2, "blocked": 0, "booked": 0, "units": 2 },
  "revokedSessions": 1
}

• revokedSessions counts buyer access sessions cascade-revoked in the same operation. An archived channel never leaves live access behind it.
• Sold seats keep the channel that sold them, forever. Archiving updates only where a seat would return to if cancelled later. Nothing is deleted, and the channel report still attributes those sales correctly.

Archive refuses to strand a buyer

If anyone is mid-checkout on the channel’s inventory, archive is blocked and tells you when to try again:

{
  "error": "channel_archive_blocked_by_holds",
  "code": "channel_archive_blocked_by_holds",
  "message": "This channel still has active holds; archive is blocked until they release or expire",
  "details": {
    "channelId": "chn_9f1c",
    "activeHolds": 1,
    "heldUnits": 1,
    "latestHoldExpiresAt": 1764600180000,
    "retryAfterMs": 179000
  }
}

409. Wait retryAfterMs and retry, or release the holds first.

Hosted access links

A hosted access link is a shareable URL a buyer opens to obtain a buyer access session for one channel, without your backend authenticating them individually. Use one when you cannot authenticate each buyer yourself — a sponsor’s guest list, a press allocation — and a buyer access session when you can.

expiresAt is an absolute timestamp, not a duration.

{
  "link": {
    "id": "alk_5b0e", "channelId": "chn_9f1c", "label": "VIP list Nov 14",
    "includePublic": false, "expiresAt": 1765200000000,
    "maxRedemptions": 100, "redemptions": 0, "maxQuantity": 4,
    "sessionTtlSeconds": 1800,
    "state": "active", "status": "active",
    "createdAt": 1764600000000, "createdBy": "user:usr_123",
    "revokedAt": null, "lastRedeemedAt": null,
    "rotatedFrom": null, "rotatedTo": null
  },
  "url": "https://app.seatlayer.io/a#alc_ZXZ0X2FiYw_7c1e",
  "capability": "alc_ZXZ0X2FiYw_7c1e",
  "revealedOnce": true
}

state is active, revoked, or rotated; status adds the derived expired and exhausted.

List, rotate, revoke

Status only — {"links": [{…, "activeSessions": 0}]}. No capability, no hash. There is no route that recovers a lost link.

Rotation is how you recover a lost link. It issues a successor inheriting every policy field and ends the predecessor. endActiveSessions is a required boolean — there is no default, because the two answers are very different:

The cascade is scoped to that link, so a session your backend minted directly for the same channel is untouched. The response adds previous and endedSessions to the create shape.

Add ?endActiveSessions=1 to cascade. The default is the gentle branch: the link stops admitting new buyers, existing sessions expire naturally.

Errors

Checklist

• Read assignmentVersion immediately before an Apply, and surface conflicts to a human.
• Treat alreadyInTarget as success, not as a skip.
• Set externalRef on every channel you will reconcile against.
• Preview the audience before a partner goes live.
• Persist a hosted link’s url at the moment of creation.
• Choose endActiveSessions deliberately — misplaced and leaked are different.
• Never treat a channel id from a client as authorization.

Next: buyer access sessions and the private and partner sales tutorial.