Your seat allocations are the seats your entity may consume at each venue, broken out by program, day of week, and time window. Use /v2/commitments to view and adjust them.

Each request is scoped to one entity at a time (see Authentication for the resolution order).

How allocations work

A commitment is a venue's contracted block of seats for a given program, day-of-week, and time window (for example, 20 seats every Monday–Friday from 17:00 to 22:00 under the Premium Dining Program). That capacity is then allocated to one or more entities — each allocation is the number of seats that entity may consume for availability and bookings.

A row returned by /v2/commitments describes one commitment with your entity's seat counts applied. The full field shape, types, and per-field semantics are documented in the API Reference under the Commitments tag — this guide focuses on assignment status and seat math.

Assignment status

Each row reports an assignment_status describing your entity's relationship to the commitment. Your entity is eligible for a commitment when its program is one your entity has access to and the parent agreement is in effect (not yet ended).

• assigned — your entity has a seat allocation on this commitment.
• unassigned — your entity is eligible for this commitment but has no seat allocation.
• ended — your entity had a seat allocation on this commitment, but the parent agreement has ended. Read-only.

GET /v2/commitments returns assigned rows by default; see Filtering for requesting the others.

Seat math

The seat counts on each row break down as:

total_seats = entity_seats + peer_seats + unallocated_seats

• total_seats — total number of seats contracted under this commitment.
• entity_seats — number of seats allocated to your entity.
• peer_seats — number of seats allocated to other entities.
• unallocated_seats — number of seats not yet allocated.

For unassigned rows, entity_seats is null and contributes 0 to the equation.

For ended rows, the seat counts are a historical snapshot of the commitment's state at the moment the parent agreement ended.

Listing your allocations

GET /v2/commitments returns your allocations as a list. Use the query parameters below to filter or paginate.

curl https://api.avvail.com/v2/commitments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Filtering

Use ?status[]= to request statuses other than the default assigned:

Two additional filters narrow the result further:

• ?venue_id=<uuid> — narrow to one venue. Useful when migrating from the deprecated seat_commitments block on GET /v2/venues/{id}.
• ?program_id=<uuid> — narrow to one program.

All filters compose. The default status[]=assigned still applies when omitted — ?venue_id=X returns your assigned commitments at venue X. To get ended commitments at the same venue, combine explicitly: ?venue_id=X&status[]=ended.

Pagination

Standard v2 ?page= / ?limit= pagination applies (see Advanced Usage for the pagination object's fields and defaults).

Pagination is filter-scoped. ?status[]=assigned&page=2 paginates the assigned rows alone — not a union with other statuses. The same applies to combined-status queries: ?status[]=assigned&status[]=ended&page=2 paginates the union of those two statuses.

Fetching a single allocation

GET /v2/commitments/<id> returns one row. It accepts any commitment id from your list response — assigned, unassigned, or ended — and the response reflects your entity's relationship to that commitment.

curl https://api.avvail.com/v2/commitments/<id> \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Setting your allocations

PUT /v2/commitments replaces your assigned allocations — the request body is the new set. Each entry in data[] carries the commitment id and your entity's seat allocation on it:

curl -X PUT https://api.avvail.com/v2/commitments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      { "id": "8f3c2b1a-8e4d-4f9c-a6b2-3d5e1a7c9f2b", "entity_seats": 8 },
      { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "entity_seats": 5 }
    ]
  }'

• Entries in the body are upserted by (your entity, commitment_id).
• Currently-assigned rows omitted from the body are unassigned.
• Re-sending the same body is a no-op: zero diff, zero audit events.
• Send "data": [] to unassign all of your allocations.
• Each entry's id must reference a commitment your entity is eligible for. Other ids return 422 Unprocessable Entity with a detail naming the rejected commitment.
• The combined entity_seats across all entities on a commitment cannot exceed its total_seats; over-allocation returns 422.

Authorization

Access to /v2/commitments follows the entities each identity is granted. A typical setup: a parent identity manages allocations for its delegated identities.

• The partner identity has commitments:update and accesses every entity it provisions. It sets the allocation for each delegate by switching entity context per request.
• Each delegated identity accesses only its own entity (or entities) and does not have commitments:update. The delegate consumes its allocation through availability and reservation flows.

If a delegate's integration needs visibility into its cap, grant commitments:read. If you want the cap to stay opaque, omit commitments:read as well — the delegate's reservations are still bound by the allocation server-side regardless of whether it can read the number.