Inventory Management

Use the Storefront API to create and manage the event catalog for your store: promoters, venues, events, tickets, and related entities.

Typical setup flow

1. Supporting entities

Create catalog metadata (order may vary):

Step	Endpoint	Purpose
Promoters	`POST /promoters`	Event organiser branding
Venues	`POST /venues`	Physical or logical location
Categories	`POST /categories`	Browse/filter grouping
Artists	`POST /artists`	Performers linked to events

2. Events

POST /api/v1/events

Required: title, start, end as UTC Y-m-d H:i:s strings (e.g. 2026-07-01 18:00:00). Responses return start and end as Unix timestamps; see Conventions.

Link related entities by ID:

{
  "title": "Summer Festival",
  "type": "standard",
  "start": "2026-07-01 18:00:00",
  "end": "2026-07-01 23:00:00",
  "venue": 1,
  "categories": [1],
  "artists": [1],
  "promoter_id": 1
}

Reserved seating (optional)

If the store has a connected Seats.io account, configure reserved seating on create or update:

{
  "reserved_seating": {
    "enabled": true,
    "event_key": "seatsio-event-key",
    "tickets": {
      "12": { "category_key": "orchestra" }
    }
  }
}

Store must have Seats.io credentials; otherwise the API returns 422 on reserved_seating
event_key is required when enabled
Map each seated ticket ID to a Seats.io category_key
Set enabled to false to clear the configuration (reserved_seating becomes null on the event)

Ticket responses expose seatsio_category_key when mapped.

3. Tickets

Create ticket types on an event:

POST /api/v1/events/{eventId}/tickets

{
  "title": "General Admission",
  "quantity": 100,
  "price": 2500,
  "booking_fee": 150,
  "type": "barcode"
}

price and booking_fee are in minor units.

4. Checkout fields (optional)

Define custom checkout questions for your storefront (non-core fields only):

GET    /api/v1/checkout-fields
POST   /api/v1/checkout-fields
GET    /api/v1/checkout-fields/{id}
PUT    /api/v1/checkout-fields/{id}
DELETE /api/v1/checkout-fields/{id}

{
  "label": "Dietary requirements",
  "type": "text",
  "is_required": true,
  "published": true
}

Field name (stable key for cart answers) is derived from label when omitted. Supported types include text, select, radio, checkbox, disclaimer, and others — see Checkout fields.

At checkout, cart detail responses include applicable custom_fields. Submit answers with PATCH /carts/{idOrToken} using custom_field_values keyed by field name.

5. Listing events for sale

For checkout integrations, list events customers can buy:

GET /api/v1/events?only_listable=1

Omit status or use any value other than all → upcoming, ok-status events only
status=all → include past/non-upcoming events

Then load tickets:

GET /api/v1/events/{eventId}/tickets

6. Devices (optional)

For door scanning or POS, see Devices in the API reference (/devices, /devices/{id}/pins).

7. Discounts

Create promo discounts and codes before checkout can apply them:

POST /api/v1/discounts
POST /api/v1/discounts/{discountId}/codes

Scope (where the discount applies)

Set scope on create (POST /discounts) or replace it on update (PATCH /discounts/{id}). Sending scope on PATCH replaces all existing applicability relations.

`scope.type`	Include	Exclude
`events`	`event_ids` — specific events	`excluded_ticket_ids` — ticket types to omit (e.g. VIP) within those events
`categories`	`category_ids` — events in these categories	—
`store`	All events and tickets in the store	—

Event scope with ticket exclusions — 10% off General Admission but not VIP:

{
  "name": "Summer 10% off (no VIP)",
  "scope": {
    "type": "events",
    "event_ids": [1],
    "excluded_ticket_ids": [5]
  },
  "discount_type": "percentage",
  "percentage": 10,
  "code_type": "single",
  "code": "SUMMER10"
}

Category scope:

{
  "scope": {
    "type": "categories",
    "category_ids": [2, 3]
  }
}

Store-wide scope:

{
  "scope": {
    "type": "store"
  }
}

Code types:

`code_type`	Meaning
`single`	One shared code at create time (optional `max_redemptions`)
`unique`	Create the discount first, then add one or more codes via `POST .../codes` with a `codes` array

Promo code strings must be unique across the entire store. At checkout, apply a code with POST /carts/{token}/discount-code (see Checkout Integration).

API reference

Full endpoint documentation:

Typical setup flow​

1. Supporting entities​

2. Events​

Reserved seating (optional)​

3. Tickets​

4. Checkout fields (optional)​

5. Listing events for sale​

6. Devices (optional)​

7. Discounts​

Scope (where the discount applies)​

API reference​