Skip to main content

Async, destructive, and idempotent operations

Most read endpoints follow the obvious REST conventions. Write endpoints — especially destructive ones like refunds, cancellations, and transfers — share a few extra rules that apply uniformly across the API. This page is the single source for those rules so individual endpoint pages don't have to repeat them.

Sync vs. async responses​

A request that completes inside the HTTP round trip returns the usual status code:

  • 200 OK — request succeeded, response body included
  • 204 No Content — request succeeded, no response body

A request that kicks off side effects that resolve after the response (for example, an order refund that goes through the payment processor, or an event cancellation that fans out emails and refunds) returns:

  • 202 Accepted — the request was accepted and the work has been queued

There is no separate "operation" or "jobs" resource to poll. Instead, the affected resource itself carries a status field — for example refund_status on an order, or cancellation_status on an event — that transitions as the work completes. Fetch the resource again to read its current state.

If you'd rather not poll, subscribe to webhooks: the relevant events fire as the resource transitions through its terminal states.

Idempotency​

Network blips are inevitable. Without protection, a client that retries a failed request can double-charge a customer, refund twice, or create the same registration twice. The API supports the standard Idempotency-Key header on every write (POST, PATCH, DELETE) so retries are safe.

See Idempotency for the full contract — header format, cache lifetime, replay semantics, the response codes you may see (409, 422, 503), and a recommended client pattern.

Side-effect flags require explicit values​

Destructive endpoints that trigger user-visible consequences — sending notification emails, refunding payments, releasing inventory back to the pool, etc. — require you to explicitly opt in to each consequence as part of the request body. There are no defaults.

For example, a cancellation endpoint will require you to set fields like send_email and refund_payments to true or false. Omitting them is a 422 Unprocessable Entity; each endpoint documents exactly which flags it requires and what each one does.

This is intentional. The Viewcy management UI confirms destructive actions through modals and checkboxes that a human reads before clicking. An API client doesn't see that UI, so the request body has to carry the same intent explicitly. Defaulting these flags to "yes, send emails" or "no, don't refund" would silently disagree with the UI half the time; defaulting to safe-but-surprising values would do the wrong thing the other half. Requiring an explicit choice keeps the contract honest.

Deleting an event​

DELETE /events/{id} is the one destructive write in the current API. It:

  • responds 200 OK with an empty body and moves the event to a terminal deleted state immediately;
  • cancels the event's future occurrences asynchronously — that work fans out in the background and fires the ticket.cancelled webhook for affected attendees;
  • does not email attendees and does not issue refunds.

It takes no side-effect flags — the conservative behavior above is fixed. See Working with events.

Webhooks​

Webhook events fire as resources transition through their terminal states — both for synchronous and asynchronous operations. If your integration needs to react to refunds, cancellations, transfers, or other state changes, subscribe to the relevant events instead of polling.

See Webhooks for the list of available events and setup instructions.

See also​