Open the purchase session (only one live per buyer)

Requires the X-Customer-Session header. The enterprise service API key is OPTIONAL (with a key, the event date must belong to the workspace pinned to it; otherwise 404). Opens THE buyer purchase session: there is ONLY one live per buyer across any tab or device, and the latest wins — the previous one becomes superseded (it can no longer create an order or start a new payment) and its seats.io hold is released, unless it backs a live sale. On seated event dates the server ISSUES the holdToken (mount the chart with session: "manual") and sets seatsDeadline: each session gets up to 3 minutes and the budget is 3 attempts (9 CUMULATIVE minutes) per buyer and event date, summing all of their sessions within a 30-minute window, and it only runs while no order has been created. Once exhausted, it responds 429 with error.code SEAT_BUDGET_EXHAUSTED, error.details.reason seat_budget_exhausted and error.details.retryAfterSeconds (10-minute cooldown; also in the Retry-After header). If the SAME browser (deviceKey) reopens the SAME event date with its session alive, it gets that same session with 200 instead of 201. Only event dates on sale: published event and current event date (otherwise 404). Limits: 10 creations per minute per buyer, 30 per minute per IP when called without an API key, and a global ceiling per event date (429 RATE_LIMITED). Once the session is created, POST /customer/orders and the payment POSTs carry the X-Purchase-Session: <id> header; when the clock runs out, call POST /customer/purchase-sessions/{id}/release.

POST/customer/purchase-sessions

Authorization

AuthorizationAPI key · headerrequired

API key prefixed with Bearer . Alternative: the x-api-key header with the raw key. Available scopes: read and write (see /.well-known/oauth-protected-resource).

x-api-keyAPI key · headerrequired

Raw API key (without Bearer ), alternative to Authorization.

Header parameters

X-Workspace-Idstring

Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).

Request body

requiredapplication/json

eventDateIdstringrequired

min length 1 · max length 64

deviceKeystringrequired

Stable browser identifier (e.g. stored in localStorage). If the SAME browser reopens the SAME event date while its session is still alive, it gets that same session (same holdToken, same clock) instead of a new one.

min length 8 · max length 200

Responses

200

The SAME browser (deviceKey) reopened the SAME event date while its session was still alive: that session is returned (same holdToken, same clock) and nothing was created.

dataPurchaseSessionCreatedrequired

Show properties

idstringrequired

eventDateIdstringrequired

statestringrequired

seatedbooleanrequired

true = the event date has a seats.io map.

holdTokenstring | nullrequired

seats.io hold token ISSUED BY THE SERVER. Mount the chart with session: "manual" and this holdToken (https://docs.seats.io/docs/renderer/config-session/), never with session: "continue". It is the ONLY token POST /customer/orders accepts for this session. null for event dates without a map.

Show properties

Any of:

string

string

null

null

seatsDeadlinestring | nullrequired

Instant (ISO 8601 UTC) until which the order with seats can be created. This is the clock to display over the map. The seats.io hold expires AFTER this instant, never before. null for event dates without a map.

Show properties

Any of:

string

string

null

null

budgetSecondsinteger | nullrequired

Budget seconds granted to this session (= seatsDeadline − now). The budget is CUMULATIVE per buyer and event date: opening another tab does not reset it.

Show properties

Any of:

integer

integer

null

null

replacedSessionIdstring | nullrequired

Live session that this one replaced (now superseded), or null. That tab can no longer create an order or start a new payment.

Show properties

Any of:

string

string

null

null

201

dataPurchaseSessionCreatedrequired

Show properties

idstringrequired

eventDateIdstringrequired

statestringrequired

seatedbooleanrequired

true = the event date has a seats.io map.

holdTokenstring | nullrequired

Show properties

Any of:

string

string

null

null

seatsDeadlinestring | nullrequired

Show properties

Any of:

string

string

null

null

budgetSecondsinteger | nullrequired

Budget seconds granted to this session (= seatsDeadline − now). The budget is CUMULATIVE per buyer and event date: opening another tab does not reset it.

Show properties

Any of:

integer

integer

null

null

replacedSessionIdstring | nullrequired

Live session that this one replaced (now superseded), or null. That tab can no longer create an order or start a new payment.

Show properties

Any of:

string

string

null

null

401

Missing or invalid credential.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsany

403

Insufficient role or resource not accessible.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsany

404

Resource does not exist or is out of scope.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsany

422

Request body/parameter validation failed.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsany

429

Too many requests: rate limit exceeded.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsany

503

Service unavailable: an external dependency is down or initialization failed.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

retryablebooleanrequired

detailsany

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

API keyRemember on this deviceInclude my values in samples

Parameters

X-Workspace-IdheaderActive workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).

Bodyapplication/json

eventDateIdstring*deviceKeystring*Stable browser identifier (e.g. stored in localStorage). If the SAME browser reopens the SAME event date while its session is still alive, it gets that same session (same `holdToken`, same clock) instead of a new one.

Request

curl -X POST 'https://admin.appfreeticket.com/api/v1/customer/purchase-sessions' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "eventDateId": "string",
  "deviceKey": "stringst"
}'

const response = await fetch("https://admin.appfreeticket.com/api/v1/customer/purchase-sessions", {
  method: "POST",
  headers: {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: "{\n  \"eventDateId\": \"string\",\n  \"deviceKey\": \"stringst\"\n}"
});

import requests

response = requests.post(
    "https://admin.appfreeticket.com/api/v1/customer/purchase-sessions",
    headers={
        "Authorization": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    data="{\n  \"eventDateId\": \"string\",\n  \"deviceKey\": \"stringst\"\n}",
)

Response

{
  "data": {
    "id": "string",
    "eventDateId": "string",
    "state": "live",
    "seated": true,
    "holdToken": "string",
    "seatsDeadline": "string",
    "budgetSeconds": -9007199254740991,
    "replacedSessionId": "string"
  }
}

{
  "data": {
    "id": "string",
    "eventDateId": "string",
    "state": "live",
    "seated": true,
    "holdToken": "string",
    "seatsDeadline": "string",
    "budgetSeconds": -9007199254740991,
    "replacedSessionId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": null
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": null
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": null
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": null
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": null
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "details": null
  }
}