BillyDocumentation

Create an event

Creates an event with one or more sessions under your organization. A venue address with at least a street address line (addressLine1) is required: its formatted form is displayed everywhere (shop, tickets, emails). Tags are free-form labels: an existing organization tag is reused when the normalized form matches (case- and whitespace-insensitive, accents kept), otherwise it is created. The response reflects the created state; the currency is your organization's currency. Note: unlike events created in the Studio, no default sales channel or pricing grid is set up yet — configure distribution in the Studio.

Preview release

This operation is only available on the preview release target — send Billy-API-Version: preview to reach it. Preview has no stability promise: its routes and payloads can change without notice, so pin a dated release before you depend on one. The playground below sends a real POST request to the live API with your own key, and will create or modify actual data.
POST
/v1/events

Creates an event with one or more sessions under your organization. A venue address with at least a street address line (addressLine1) is required: its formatted form is displayed everywhere (shop, tickets, emails). Tags are free-form labels: an existing organization tag is reused when the normalized form matches (case- and whitespace-insensitive, accents kept), otherwise it is created. The response reflects the created state; the currency is your organization's currency. Note: unlike events created in the Studio, no default sales channel or pricing grid is set up yet — configure distribution in the Studio.

Authorization

HTTPBearer
AuthorizationBearer <token>

API key authentication. Format: Bearer billy:o:<organization_id>:<api_key>

Example: Bearer billy:o:yyyyyyyyyyyyyyyy:xxxxxxxxxxxxxxxxx

In: header

Header Parameters

Billy-API-Version*string

Requested API version. Current context: preview.

Default"preview"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for POST /v1/events.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/events" \  -H "Billy-API-Version: preview" \  -H "Content-Type: application/json" \  -d '{    "title": "Jazz Night",    "venueAddress": {      "addressLine1": "211 avenue Jean Jaurès"    },    "eventTimezone": "Europe/Paris",    "eventSessions": [      {        "startAt": "2026-11-15T20:30:00+01:00",        "durationMinutes": 90      }    ]  }'
{  "id": "evt_64f1c2a9e8b4a12f9c0a1234",  "createdAt": "2025-01-15T10:42:31.000Z",  "updatedAt": "2025-01-20T09:12:05.000Z",  "title": "Electro Night Festival",  "description": "An immersive electronic music experience with top international DJs.",  "imageUrl": "https://cdn.example.com/events/electro-night/banner.jpg",  "venueName": "La Grande Halle",  "venueAddress": {    "addressLine1": "211 Avenue Jean Jaurès",    "addressLine2": null,    "city": "Paris",    "postalCode": "75019",    "countryCode": "FR"  },  "eventTimezone": "Europe/Paris",  "currency": "EUR",  "sessionCount": 1,  "firstSessionStartAt": "2025-03-21T19:30:00+01:00",  "lastSessionStartAt": "2025-03-21T19:30:00+01:00",  "nextSessionStartAt": null,  "nextSessionId": null,  "tags": [    "concert",    "electro"  ]}