API Reference

Authentication

Every endpoint except Register and Login authenticates with an API key sent in the X-API-Key header. There are two ways to get one:

• Open Settings in the admin panel and choose the Developers tab. Under API Settings, switch on Enable API Access and press Save. The key is shown once, beside a copy button, so copy it before you leave the page. See Account Settings.
• Call the Register or Login endpoints, which return a key in the response body (useful for AI agents and scripted setup).

A key belongs to a user account, not to one schedule. It can reach every schedule where you are the owner or an admin, and nothing else. Followers and viewers cannot be used to authorise API calls.

On the hosted service a team belongs to the Enterprise plan. The schedule's owner's key works on Pro or Enterprise, but a team admin's key reaches a schedule only while that schedule is on Enterprise. Below that, the lists leave the schedule and its events, sales and fan content out, and every call on it answers the admin 403 Unauthorized.

Plan requirement

On the hosted service, a schedule must be on a Pro or Enterprise plan for the API to see it. The schedule, event, sale and feedback lists leave out anything that belongs only to free schedules, and single-record reads and writes on a free schedule return 403 API usage is limited to Pro accounts. A few endpoints carry no plan check at all: Create Schedule, so a new account can bootstrap; Delete Schedule, so an owner can always retire one; Create Sale, so a schedule can record a sale it took elsewhere; both List Categories routes; List Fan Content; and the Boosts endpoints, which answer only a boost partner's own key. A new schedule starts on the Free plan with no trial. Selfhosted installs resolve to Enterprise, so every endpoint is available there.

Key lifetime and rotation

• A key expires one year after it is issued. After that every request returns 401 API key expired. API Settings shows the expiry date under the key, and says so once the key has expired.
• Keys are stored hashed, so a lost key cannot be recovered. To rotate one, switch Enable API Access off and press Save, then switch it on and save again. The first save deletes the old key at once, after asking you to confirm, and the second issues a new one.
• Ten consecutive requests with the same invalid key block that key for 15 minutes with 423 API key temporarily blocked.
• A request with no X-API-Key header returns 401 API key is required, and an unknown key 401 Invalid API key.
• A key whose account the operator has blocked returns 403 Account blocked on every request, and Login gives such an account no key.

Rate Limits

Authenticated requests are counted per account, in separate read and write buckets. Each key has budgets of its own, so callers that share an address (a voice-agent platform, an office network) do not share them, and a request that fails authentication is not counted there:

Each bucket counts in a fixed one-minute window that opens with its first counted request. When that minute is up the count starts again from zero, so a client that makes no more than 300 reads and 30 writes in any one window is never refused, however long it runs.

Requests that prove no key, with no X-API-Key header or a wrong one, are counted per IP address instead (the visitor's own, not a proxy's): after 30 in a minute that address is answered 429 until the minute is up, except for a key it has already used successfully in the last day.

Create Event carries a second throttle of 30 requests per minute on top of the write bucket. It is counted per account, across all your schedules, in a window of its own, so a bulk import should pace itself well below 30 creates a minute.

Unauthenticated endpoints

The auth endpoints are limited separately, because they run before any key exists:

The read and write buckets and the three endpoints above all answer 429 with an error message when the limit is hit. A 429 from a read or write bucket also carries a Retry-After header with the number of seconds until that bucket's window resets. The three auth endpoints send no rate limit headers, so back off on the status code there.

The Create Event throttle answers differently, because it is the framework's own: its 429 carries Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining headers, and its body holds a message in place of error. See Response Format for why that request needs an Accept header.

Response Format

Every endpoint answers in JSON. Successful responses wrap the result in a data property: an object for single-record endpoints, an array for list endpoints. List endpoints add a meta object with the pagination counters. Event and sale writes and Upload Flyer put a confirmation in meta.message, while the delete endpoints return theirs as data.message.

Failures return an error string. A validation failure adds an errors object keyed by field name, each holding an array of messages.

Ask for JSON

Send Accept: application/json with every request. A failure raised outside an endpoint is rendered by the framework, which picks its format from that header. Without it, the Create Event throttle, an unknown URL, an unknown venue_id and a server error come back as HTML pages, and the daily cap on new events comes back as a redirect. With it they are JSON, though the framework's own replies name the reason message, not error.

Record IDs

Schedules, events, sub-schedules, tickets and sales are all identified by an opaque encoded string such as "w4K8xU", never by the raw database number. Pass the same string back exactly as you received it. The examples on this page use readable stand-ins such as "evt123". Category IDs are the one exception: they are plain integers.

Dates and times

Pagination

Every paginated list endpoint (schedules, events, sales, feedback, fan content and boosts) takes the same two query parameters. The other lists (sub-schedules, categories, appointment types, open times and boost statements) come back whole.

The meta object

Every paginated response returns the same seven counters. Keep requesting page + 1 until it equals last_page.

Register

Registration takes two steps: send a verification code to the email address, then register with the code.

Step 1: Send Verification Code

No authentication required. Takes a single email parameter and emails a 6-digit code that is valid for 10 minutes, answering 200 with a confirmation in data.message. Rate limited to 5 codes per email per hour. An address that already belongs to a full account is rejected with a 422.

A new code replaces the one before it, and a code can be tried once: registering with a wrong verification_code uses it up, so request another.

Step 2: Register

No authentication required. Rate limited to 3 registrations per IP per hour. On success it returns 201 with an API key that is valid for one year, and the account's email is treated as verified.

An address that already has a full account is refused with a 422. An address that has an account waiting for its owner (an invited team member, or somebody who bought a ticket) is taken over by the registration, since the code proved you read that inbox.

Both steps watch a hidden website honeypot field. Leave it out entirely: sending any value in it returns 422 Invalid request.

Login

No authentication required. Exchanges an email and password for an API key valid for one year.

Other refusals to handle: an account the operator has blocked returns 403 Account blocked, an account with two-factor authentication enabled returns 403 and must generate its key from Settings instead, and a wrong email or password returns 401 and counts toward the 5-per-15-minute limit. A successful login clears that count.

List Schedules

Returns a paginated list of the schedules where you are the owner or an admin. Deleted schedules are excluded, and on the hosted service so are schedules that are not on a Pro or Enterprise plan. Each row carries the schedule's sub-schedules in a groups array.

Show Schedule

Returns a single schedule by subdomain, including its sub-schedules in a groups array. You must be the owner or an admin of it, otherwise the response is 404. A schedule that is not on a Pro or Enterprise plan returns 403, and so does one you are a team admin of while it is not on Enterprise (hosted only, see Authentication).

The schedule object

List, Show, Create and Update Schedule return this shape. A field with nothing stored is null.

Create Schedule

Create a new schedule. There is no plan gate here, so a new account can bootstrap itself, but the schedule starts on the Free plan with no trial and most other endpoints need it on Pro or Enterprise, so on the hosted service subscribe before you start pushing events. You are attached to the new schedule as its owner, and it becomes your default schedule if you had none.

What comes back

The reply is 201, and data holds the schedule object, generated subdomain included. This is the one place the object is returned for a schedule on the Free plan, so you can read what you made. Show Schedule answers 403 for it and List Schedules leaves it out until it is on Pro or Enterprise.

Hosted limits and verification

On the hosted service one account may own up to 50 schedules. Beyond that the endpoint returns a 422.

On the hosted service a schedule is not public until its contact email or phone number is verified: until then its pages answer visitors with a 404, so search engines never see them. Leave email out, or send your account's own address, and the schedule shares your account's verification; any other address is sent a verification link. A selfhosted install treats every new schedule as verified.

Update Schedule

Update a schedule. Include only the fields you want to change; anything you omit is left alone. Takes the same fields as Create Schedule apart from type: neither the schedule type nor the subdomain can be changed through the API, and any other field in the request is ignored. Requires owner or admin access and a Pro or Enterprise plan. Returns the schedule object.

On the hosted service, changing email clears the schedule's email verification and sends a verification link to the new address. Unless its phone number is verified, the schedule's pages stop being public until that link is followed.

Branding, images, layout and integrations are not exposed here. Edit those in the admin panel, on the Style, Page content, Settings and Integrations tabs of the schedule form.

Delete Schedule

Retire a schedule. Requires owner access but no plan: an admin gets a 404. There is no undo through the API.

The schedule is flagged as deleted and stops appearing anywhere, and the call also:

• Deletes its profile, header and background images from storage
• Deletes its analytics history (page views, referrers and appearances)
• Tears down its Google Calendar and Outlook sync subscriptions
• Cancels any running boost campaign and refunds it where money is owed
• Emails the schedule's members to tell them it was deleted
• Returns any newsletter waiting for its send time to a draft
• Frees its subdomain for anyone to register, keeping the old name on record so a platform admin can restore the schedule

Events are not swept up automatically. The exception is a talent schedule: an event whose only member was that schedule is deleted with it, so nothing is left orphaned.

A schedule with a paid plan has its subscription cancelled first, at once and not at the end of the billing period. If that cancellation fails the reply is 502 and nothing is deleted, so the call is safe to repeat.

List Sub-Schedules

List every sub-schedule on a schedule, returning id, name, slug and color for each. Requires owner or admin access and a Pro or Enterprise plan. The response is not paginated.

Sub-schedules group and colour-code events so visitors can filter your calendar. They do not control who can see an event: use the visibility flags on Create Event for that.

Create Sub-Schedule

Create a sub-schedule on a schedule. Requires owner or admin access and a Pro or Enterprise plan. The slug is generated from the name and is what you pass as the schedule parameter when creating an event.

When the schedule's language is not its translation language (English unless changed), the name is machine-translated into the translation language and the slug is built from the translated name. So on any schedule not in English, read the slug back from the response rather than deriving it yourself.

Update Sub-Schedule

Update a sub-schedule's name or colour; send only the one you want to change. Requires owner or admin access and a Pro or Enterprise plan. Changing the name regenerates the slug, which changes the value events must pass in schedule, so re-read it from the response.

Delete Sub-Schedule

Delete a sub-schedule. Events assigned to it are kept and simply lose the assignment. Requires owner or admin access and a Pro or Enterprise plan. Pass the encoded sub-schedule id from List Sub-Schedules.

List Events

Returns a paginated list of the events you may read with Show Event, newest start date first: those your schedules own, those on a venue or talent schedule of yours, and those you made on a schedule you still run. An event a curator schedule of yours only lists, or one a schedule of yours turned down, is left out. On the hosted service an event is only listed if at least one of its schedules is on a Pro or Enterprise plan. Appointment bookings are never returned here; they are not calendar events.

Drafts, internal, unlisted and cancelled events are all included, so check is_draft, is_internal, is_private and is_cancelled before republishing a row on a public site. Each row is the event object.

Show Event

Returns a single event by its encoded ID, including its ticket types, add-ons, members, agenda parts, venue, recurring configuration and visibility flags. Requires a Pro or Enterprise plan, and that you are an owner or admin of a schedule the event is on, or made it and still run the schedule that owns it. A curator schedule counts only for the events it owns: one that only lists somebody else's event gets 403, and so does a schedule that turned the event down.

An appointment booking, which List Events leaves out, can be read here by its event ID. Book an Appointment returns the booking's sale ID; Show Sale with that ID gives the event_id.

The event object

List, Show, Create, Update, Cancel and Restore Event and Upload Flyer return this shape, and so do the event.* webhooks. A field with nothing stored is null, except the few marked as present only in some cases.

Create Event

Create an event on the schedule identified by {subdomain}. Requires owner or admin access on that schedule and a Pro or Enterprise plan. This endpoint carries its own throttle of 30 requests per minute in addition to the write bucket. On success it returns 201 with the event object. The schedule you post to becomes the event's owner, the one that sells its tickets and sees its sales, and no later request can change that.

Only the parameters listed here are read. Anything else at the top level of the body is dropped before the event is saved, so settings the API has no field for (sponsors, the event's checkout questions, promo codes, the Checkout and Sales rules options, seating) are made in the admin panel.

Core fields

Visibility

Send no visibility flag at all and the event inherits the schedule's default for new events. Unlisted and Internal need an Enterprise plan Enterprise - Requires the Enterprise plan ; on any lower plan they are stripped and the event is saved as a Draft so it never publishes by accident.

The draft default is applied even to a partial request that omits is_draft, so on a drafts-by-default schedule you must send is_draft: false to publish straight away.

Recurrence

The recurrence fields only take effect in a request that also carries schedule_type: "recurring". Without it a new event is a single one, whatever else is sent.

Tickets, RSVP and add-ons

Every row you send in tickets, addons or event_parts is a new row on a new event. An id copied from a read of another event is ignored. On Update Event the same id is what addresses an existing row.

Other ticket settings

A ticket row also carries the settings the admin panel gives a ticket type: its own questions (custom_fields), a seating band (seating_band), and whether it is a pass (is_pass and the pass_* settings). These are not part of the documented API: set them in the admin panel. A row you send back with its id keeps them. A row that names one of them changes it, in the shape the admin panel stores, so leave them out of what you write unless you copied them from the event as stored.

Payment method

The API stores any method from the list without checking that it is connected on the account or can settle the event's currency, so check both yourself: payfast only settles events priced in ZAR, razorpay only events priced in INR, and paypal only the currencies listed under Connecting PayPal, which is PayPal's own list minus the Hungarian forint, Japanese yen and New Taiwan dollar.

On create, omitting the field uses the installation's DEFAULT_PAYMENT_METHOD if one is set and is usable for the event's currency, falling back to cash; send null to mean cash explicitly. On update, omitting it leaves the stored value alone.

Agenda, venue and performers

What the schedule's type decides

The schedule you post to is always on the event, in the place its type gives it:

• Venue. It is the event's venue. venue_id and the name and address pair are overridden.
• Talent. It is the event's one performer. members is overridden, so other performers cannot be added through a talent schedule.
• Curator. The event is listed on it, and takes its venue and performers from the request.

End time

An event is stored as a start and a length. If your system keeps a start and an end, send ends_at and the length is worked out for you, from the two moments in UTC. An event that runs across a clock change is as long as the time that actually passes: 8pm to 8pm over the night the clocks go forward is 23 hours.

• ends_at has to be after the start and at most 8760 hours after it. On an update that does not send starts_at it is measured from the stored start.
• Send one of ends_at and duration. The event object carries both, so a client that reads an event and writes it back sends both, and that is accepted: the one that differs from the stored value is taken as the change. Change both to values that disagree and the reply is 422.
• Move only starts_at and send the rest back as read, and the event moves whole: it keeps its length and ends later. That holds when the new start is past the old end too, as when an event is postponed by a day: an ends_at that comes back exactly as it was read says nothing.
• "ends_at": null changes nothing. To take the length off an event, send duration as null or 0.

Flyer from an address

Send flyer_image_url and the picture at that address becomes the event's flyer, in the same call. It is downloaded once and stored as a file of ours, so the event does not depend on the address afterwards, and the flyer_image_url you read back is our copy's address, not the one you sent. To send a file of your own instead, use Upload Flyer.

• The address has to be public and answer within 10 seconds with a JPEG, PNG, GIF or WebP of at most 8 MB. What kind of picture it is, is read from the file itself, not from the address or the server's content type.
• The picture is fetched before anything is saved. If it cannot be had, the reply is 422 with the reason under errors.flyer_image_url, and the event is not created or changed.
• A picture wider or taller than 2,000 pixels is resized to fit. An animated GIF is stored as it is.
• On Update Event, a new address replaces the flyer and null removes it. The address the event already reports is no change, so an event that is read and written back keeps its flyer and nothing is downloaded. Nor is the address the flyer was last fetched from: a sync that sends its own picture address with every write downloads it once. To fetch that address again after the picture behind it changed, send null first, or use Upload Flyer.

External ID

external_id is the id your own system knows an event by: a post number, a row's key, a UUID. Send it when you create an event, and your next sync can find that event again instead of adding a second one. It is returned in the event object and in every event webhook, and GET /api/events?external_id=... looks an event up by it.

• It is unique for the schedule that owns the event, so two schedules fed by two systems may both have an event numbered 1. An event that has none reads null.
• It is compared exactly: aB3 and Ab3 are two ids. A number is stored as its digits, and spaces around the value are dropped.
• Creating an event with an id the schedule already has an event for returns 409, with that event's id under data, and nothing is created, unless the request asks to update it instead. Two requests that carry the same new id at the same moment end the same way: one creates the event, the other gets the 409.
• Update Event sets it on an event that has none, changes it, or clears it with null. An update that does not mention it leaves it alone. Only an owner or admin of the schedule that owns the event can change it, and an id another event of that schedule holds is refused with 422.
• The admin panel neither shows nor changes it, and editing an event there keeps it.

Create or update in one call

A sync usually does not know whether it has sent a record before. Send "upsert": true with an external_id and this endpoint decides: the first call creates the event and returns 201, and every later call with the same id updates that event and returns 200. meta.created says which happened.

• The update follows the rules of Update Event, not the rules above. Nothing is required, a field the request does not carry keeps its stored value, and none of a new event's defaults are applied again: an event you turned into a draft in the admin panel stays a draft when the source sends it again.
• That includes the lists. Send tickets, addons or event_parts only when you mean to change them, and send each existing row with its id: a row without one is a new row, and a stored row the list leaves out is retired, as an update does.
• The update is not counted against the daily cap.
• upsert without an external_id is refused with 422, because there is nothing to match on.
• The event is looked up among the events this schedule owns. An event another schedule owns is never matched, even when this schedule lists it.

curl -X POST "https://eventschedule.com/api/events/your-schedule" \
         -H "X-API-Key: your_api_key" \
         -H "Content-Type: application/json" \
         -d '{"external_id": "post-4686933", "upsert": true, "name": "Spring concert", "starts_at": "2026-05-09 17:30:00"}'

Daily cap

The hosted service caps how many events one schedule, and one account across its schedules, may create in a day, as an anti-abuse measure. The shipped defaults are 500 a day per schedule on Pro, 1,000 on Enterprise and 100 during a trial, and three times that per account. A bulk import that trips the cap gets a 422 whose body carries "code": "event_create_limit" beside error, so it can stop at the first refusal and resume the next day. Selfhosted installs have no cap.

Update Event

Update an event by its encoded ID. Takes the same parameters as Create Event, and supports partial updates: send only the fields you want to change. Requires a Pro or Enterprise plan. Returns 200 with the event object.

Who may update is who may read it with Show Event; anybody else gets 403. The update runs through one of the event's schedules that you own or administer, which decides the timezone starts_at is read in and where a schedule slug is looked up.

What an update leaves alone

A field the request does not carry keeps its stored value. That covers the start time, the visibility flags, the recurrence, the payment method, the lists of ticket types, add-ons and agenda parts, the venue, the performers and the other schedules the event is listed on. The schedule that owns the event never changes, and the event's external_id stays unless the request names it.

What the request does not mention stays as the admin panel left it: promo codes, each ticket type's Max Per Order, volume discount, questions and pass settings, the dates added to or skipped from a series, sponsors and the event's checkout questions. An update that only renames an event changes its name.

A venue, performer or listing the request does not name also keeps its answer. One that had not yet accepted the event, or had turned it down, is still in that state afterwards: an update does not accept an event on a schedule's behalf. venue_id, venue_name and venue_address1 sent as null name no venue, so the event stays where it is.

• To change the recurrence, send schedule_type with the full set of recurrence fields, since one left out goes back to its default. Without schedule_type the stored frequency, interval and end rule are kept and those fields in the request are ignored; only days_of_week is still applied. schedule_type: "single" turns a recurring event into a single one.
• schedule moves the event to another sub-schedule. There is no way to take an event out of a sub-schedule through the API.
• A visibility flag takes effect as on create: Unlisted and Internal need Enterprise, and is_internal: true also makes the event a Draft.

What an update replaces or removes

Some schedules always stay on the event: the one the update runs through, the one that created it, and any that sit outside your account. The schedules an event is listed on cannot be named in a request, so the API neither adds nor removes one.

Delete Event

Permanently delete an event. Only the event's own people can: whoever made it, or an owner or admin of the schedule that owns it. A schedule that only lists the event answers 403, and can take the event off its own list in the admin panel instead (the API has no call for that). Requires a Pro or Enterprise plan. There is no undo, so if you may want it back, hide the event with is_draft or cancel it instead.

An event that has sales is not deleted. The reply is 422 and nothing changes, whether those sales are paid, refunded or cancelled, because the sale records would go with the event. A sale removed with Delete Sale no longer counts. Cancel it instead, which keeps the records and lets you tell the buyers.

Deleting also removes the synced copy from any connected Google Calendar, Outlook calendar and CalDAV calendar, cancels any running boost campaign, and deletes its gallery photos and sponsor logo files. An event a feed made is not made again by that feed. Unless the event was a draft, an event.deleted webhook is sent with the event's final state.

An appointment booking is the exception. It is cancelled, not deleted: the slot is freed, the booking and its sale are kept, the guest of a booking that was still live is emailed, and no webhook is sent. That reply is a bare {"message": "Appointment cancelled"} with no data wrapper.

Cancel Event

Call an event off without deleting it. The event keeps its page, which now says it is cancelled, and it keeps every sale and registration. It leaves the schedule's public calendar, stops selling, and is removed from any connected Google Calendar, Outlook calendar and CalDAV calendar. Any running boost campaign is stopped and refunded (one that runs in a boost partner's own ad account is stopped; it was never prepaid here), and installment plans stop charging. Requires a Pro or Enterprise plan, and to be the event's own: the user who created it, or an owner or admin of the schedule that owns it. A schedule that only lists the event answers 403, and can take the event off its own list in the admin panel instead.

This is the way to stop an event that has sales, which Delete Event refuses. Sales are not refunded by this call: refund each one through Update Sale or in the admin panel.

Send notify_attendees as true to email the people who bought, registered or asked to be told, with an optional message of up to 280 characters under it. Buyers are emailed only when the schedule sends from its own address. Nobody is emailed about a draft, and nobody is emailed unless you ask.

Unless the event is a draft, an event.cancelled webhook is sent. Cancelling an event that is already cancelled changes nothing and answers 200. An appointment booking is cancelled through its sale, which frees the slot and emails the guest, and sends no webhook. The reply is the event object.

Restore Event

Undo a cancellation. The event returns to the public calendar and to connected calendars, and sales reopen. Requires a Pro or Enterprise plan, and, as cancelling does, to be the event's creator or an owner or admin of the schedule that owns it.

Nobody is emailed. A boost campaign or an installment plan that the cancellation stopped stays stopped. Unless the event is a draft, an event.updated webhook is sent, with is_cancelled back to false.

Restoring an event that is not cancelled changes nothing and answers 200. An appointment booking cannot be restored and answers 422: its slot was freed when it was cancelled.

Upload Flyer

Set the flyer image for an event. Send it as multipart/form-data in a flyer_image field, not as JSON. Requires the access Show Event asks for and a Pro or Enterprise plan.

The response is the full event record, so you can read the new flyer_image_url straight back from data. To remove a flyer, send "flyer_image_url": null to Update Event. To set one from an address instead of a file, in the same call that creates the event, see Flyer from an address.

List Categories

Returns the built-in event categories with their integer IDs and English names. Pass an id as category_id when creating or updating an event. The list is not paginated.

Categories for one schedule

A schedule can rename, remove or add categories of its own, and category_id is validated against that effective list rather than the global one. Call this variant to get the exact set a given schedule will accept, and use it whenever the schedule has customised its categories. It returns the same id and name pairs, and 404 for a subdomain that does not exist.

List Sales

Returns a paginated list of sales, newest order first, each as the sale object. Deleted sales are excluded, and on the hosted service so are sales on schedules that are not Pro or Enterprise. RSVP registrations appear here too, as zero-value paid sales.

The list covers events your account created, events one of your schedules created, and events another schedule created that your venue or talent schedule has accepted. A curator schedule that only lists somebody else's event does not open that event's sales, here or on the other sale endpoints.

Show Sale

Returns a single sale by its encoded ID. Requires owner or admin access on the event's schedule and a Pro or Enterprise plan. A sale that exists but is not yours to read returns 403; a deleted or unknown one returns 404.

The sale object

Every sale endpoint except Delete Sale returns this shape, and so do the sale.* webhooks. There is no currency field: read the event's ticket_currency_code.

Guests, orders and amounts

An order bought for several named guests is stored as one row per guest, all sharing a group_id. The row with is_primary set to true holds the totals for the whole order; the other rows report zero so you do not double-count when you add them up. Every row in a group belongs to the same event.

A purchase that covered several events shares an order_id instead, one row per event, with is_order_primary on the anchoring row. The two nest: a leg of an order can itself be split across named guests, so a row may carry both.

payment_amount is what the buyer agreed to pay, not what has been collected. The two differ for a sale bought on an installment plan: the sale reads paid with the full total from the first payment onwards, because the ticket is issued then, while the rest arrives over the following months. Reconcile against Stripe rather than against this field if you are counting money in the bank.

Create Sale

Record a sale against an event, for example when someone paid you at the door or through a channel Event Schedule does not handle. You must be an owner or admin of a schedule the event is on, or have made it and still run the schedule that owns it; a curator schedule that only lists somebody else's event gets 403, because the sale settles into the event owner's account. The event must have ticketing enabled and still be selling, and each ticket is checked individually, exactly as guest checkout does: a priced row needs the schedule to be on Pro or Enterprise, while a zero-price row sells on any plan. Until the schedule is on a paid plan, though, the sale does not appear in List Sales, and Show Sale and Update Sale Status return 403 for it, so mark it paid from the Sales page instead.

What happens on success

• The reply is 201 with the sale object, secret included, since your key placed the sale.
• The sale is created as unpaid. You cannot set the status from the request; use Update Sale Status once you have the money.
• A sale whose total comes to zero is marked paid immediately.
• Any volume discount configured on the ticket type is applied to the total.
• On an event with allocated seating, the best available seats are assigned, since this path has no seat picker.
• A sale.created webhook fires, plus sale.paid for a zero-total sale.

Inventory is checked under a lock, so you cannot oversell through this endpoint. Common 422 replies are a past event or occurrence, an event_date that is not one of the event's dates, a ticket whose sales window has not opened or has closed, and a quantity larger than the remaining stock, which reports how many are left.

Update Sale Status

Move a sale to a new status by sending an action. Requires owner or admin access on the event's schedule and a Pro or Enterprise plan. Which actions are available depends on where the sale is now; an action the current status does not allow returns a 422 naming both. refund asks one thing more, because the money leaves the event creator's account: the schedule you act through must have created the event or accepted its place on it, or the reply is 403. A change that goes through returns 200 with the sale object in its new state.

Cancelling or fully refunding releases the seats back into stock and notifies anyone on the waitlist for that date; a partial refund does neither. A named guest's row inside a group_id returns 403: act on the group's primary row (is_primary), which carries the change to every guest. On a multi-event order the row with is_order_primary carries it to every leg, while acting on any other leg changes only that leg and its own guests.

Refunds

For a Stripe, PayPal or Razorpay sale, refund sends the money back through the provider and then updates the status. Send an optional amount to return part of it; omit it and the whole remaining balance goes back. A partial refund leaves the sale paid, fires no webhook, and returns 200 with the message Partial refund sent.

Every other method - Invoice Ninja, Payfast, a payment link, cash, or a sale marked paid by hand - only records the refund and backs the amount out of your revenue figures, and it ignores amount: the whole sale is recorded as refunded. Issue the money in your payment provider, then call this to keep the two in step.

It does not work the other way round. A refund issued from the Stripe, PayPal or Razorpay dashboard is not reported back to Event Schedule, so the sale stays paid and its tickets keep scanning. Refund through this endpoint or the Sales page instead.

A refund the gateway refuses returns 422 and leaves the sale paid. A refund whose outcome could not be confirmed returns 409: nothing is retried automatically, because retrying a refund that may already have gone through is how one refund becomes two. Check it against your provider before acting.

Send an idempotency_key of your own, up to 64 letters, digits, _, ., : or -, to make retrying safe. A repeat carrying the same key returns the first attempt's outcome instead of issuing a second refund, and a repeat sent while the first is still running returns 409. Without a key, a retried request is a second refund.

A payment plan is refunded in full only: sending amount for one returns 422. Each collected payment goes back separately, and an attempt that stops partway can be repeated to return the rest.

Delete Sale

Remove a sale from your records. It is cancelled first, so its seats return to stock, and then flagged as deleted: it stops appearing in List Sales and in the admin panel, and Show Sale returns 404 for it. Requires owner or admin access on the event's schedule and a Pro or Enterprise plan.

Deleting the row with is_order_primary deletes the whole multi-event order, and deleting a group's primary row deletes its guests with it. A named guest's row returns 403.

Deleting moves no money and sends no webhook, not even sale.cancelled. To give a buyer their money back, refund the sale first.

List Feedback

Returns a paginated list of post-event feedback, meaning the star ratings and comments attendees leave after an event, for schedules you own or administer. Newest first. Read only: there is no endpoint for creating or deleting feedback.

Only feedback attached to a paid, undeleted sale is returned, which is the same rule the guest page applies, so a cancelled or refunded order's rating never shows up here. On the hosted service the schedule must be on a Pro or Enterprise plan, since collecting feedback is itself a Pro feature.

List Fan Content

Returns fan comments, photos and videos submitted on events for schedules you own or administer, all three kinds merged into one feed, newest first. Approved items only by default, which is what you want when displaying them on an external site. Submitter email addresses are never included. Read only: approve and reject submissions in the admin panel.

Each kind of submission has its own id sequence, so an id is only unique within a type. Key on the two together when storing rows from this feed.

Every row carries the fields in the example. What follows them depends on the type: a comment has comment, a photo has photo_url, and a video has youtube_url and embed_url. event_part_id is the agenda part the submission was made on, or null.

List Appointment Types

The appointment types a guest can book on this schedule right now, the same list its /book page shows. The three appointment endpoints are written for an agent that talks to the guest, such as a voice agent answering the phone: every time comes with a sentence it can read out. The key's account must be an owner or admin of the schedule, and the schedule must be on Pro or Enterprise.

On the hosted service a schedule needs its own email settings to send appointment mail, and a guest booked through the API is told about the booking, or sent a way to pay, only by email. Until those settings are in place, types with a price or an approval step are left out of this list, because the guest hears about payment, or the schedule's answer, only by email.

The list is not paginated. Its meta carries the schedule's subdomain as schedule, and its timezone.

The appointment type object

List Open Times

The times still open for a type, from the same rules the booking page uses: the weekly hours, date overrides, buffers, minimum notice, the booking window and what is already booked. Each slot carries its start as a UTC instant, to send back when booking, and a label in the schedule's timezone and language to read to the guest.

When the range has nothing open, meta.next_available is the first open time after it, so the agent can offer that rather than say there is nothing. meta also carries the type's appointment_type_id. A type that List Appointment Types does not offer answers 422.

Book an Appointment

Book a time for a guest. The booking is the guest's: your account does not become its buyer, and the owner's Bookings list and booking email say it was booked through the API, so a misheard name or address is checked.

What comes back

201 with the booking. Its status is one of:

• confirmed: booked. The guest is emailed a confirmation with a calendar invite.
• pending_approval: the schedule confirms bookings by hand. The time is held, and the guest is emailed when it is confirmed or declined.
• awaiting_payment: the type is paid online. The guest is emailed a link at once, and the time is held until pay_by; unpaid by then, it is released.

The booking's id is its sale's ID: read the sale with Show Sale, whose event_id is what Cancel Event takes to cancel the booking. Beside the fields in the example the booking carries appointment_type_id, appointment_type, ends_at, timezone, the guest's name, email and phone, and price and currency (null when free). pay_by is null unless the time is held for a payment. A sale.created webhook is sent.

manage_url is the guest's own page for the booking, absolute, where they pay, change the time or cancel. emails_sent says whether the guest was emailed, and summary is a sentence for the agent to read back, such as "I've emailed a payment link to j…@gmail.com; your time is held until Tuesday, October 20 at 3:30 PM EDT."

A taken time

If the time went in the meantime the answer is 409 with "error": "slot_taken" and alternatives: the three open times nearest the one asked for, each a slot with its label. The same guest already holding that exact time is 409 with "error": "already_booked", with that booking, so a retry whose first answer was lost can read it back. A 422 lists what is wrong per field, or says the type is not taking bookings, or that the schedule has reached its daily cap on new events, which bookings count against.

Retrying safely

Send an Idempotency-Key header (up to 64 letters, digits, dots, colons, dashes or underscores) and a repeat of the same request with the same key in the next 24 hours answers with the booking the first one made, marked Idempotent-Replayed: true, instead of booking the guest twice. The same key on a different request is a 422. Only a booking is remembered, so a request that was refused can be retried with its key.

List Boosts

For a network that runs the boosts on its schedules under its own Facebook Page and Meta ad account. These endpoints answer only the key of the account that is the boost partner; any other key, a team member's included, gets 403. A boost launches when its current version is approved and its current budget is paid, in either order. Repeating an approval, a decline, a payment confirmation or a stop answers the boost as it stands, so a retry after a timeout is safe; a different decision on a boost that has moved on answers 409.

updated_since returns every boost changed at or after that time. Timestamps are whole seconds, so keep the last updated_at you saw and drop the duplicates.

The boost object

Filters: status, schedule (a subdomain), updated_since, and page / per_page (up to 500). Rows come oldest change first, by updated_at.

Get a Boost

One boost with its exact ad, its approval, its payment and its spend.

Approve a Boost

Approve the version you reviewed, with an optional note. A version that is not the current one answers 409 with the code stale_version, so an approval of earlier wording can never launch later wording.

Decline a Boost

Send it back with a note (required). The business sees the note and can edit and send it again.

Confirm a Payment

Record that the business paid you for this budget: your own reference and amount (and optionally currency), returned on the boost and on the statement. The amount is not compared with the budget. Send the budget.amount you charged for as budget: if the business has changed the budget since, the confirmation is refused with a 409 (stale_budget) rather than launching the new budget on this payment. A changed budget clears the confirmation.

DELETE /api/boosts/{id}/confirm-payment withdraws the confirmation before the boost launches, for a refund or a dispute.

Stop a Boost

Pause the campaign at Meta at once and end it, with an optional reason. A stopped boost does not restart.

Boost Statements

GET /api/boost-statements lists the monthly statements, newest first. GET /api/boost-statements/2026-11 answers one month: a line per campaign with its spend that month, the fee (your agreed rate of it, 20% unless agreed otherwise) and any adjustment for spend Meta corrected in an earlier month (that line's month names it), with the totals and the charge to your card (pending, paid, failed, action_required or carried, when the amount is too small to charge and moves to the next month). A month with spend in two currencies has a statement for each: add ?currency=EUR to pick one.

Error Handling

The API uses standard HTTP status codes, and every endpoint returns the reason as a JSON error string. The few failures raised outside an endpoint carry message in its place, and need an Accept header to be JSON at all: see Ask for JSON.

A 422 covers two different things. A schema problem carries an errors object and is worth surfacing field by field; a business refusal carries only error and reads as a sentence. Check for errors before assuming its shape.