orders = seatlayer.orders().listEventOrders("summer-gala");
+String csv = seatlayer.orders().exportEventOrdersCsv("summer-gala");
+seatlayer.orders().refundEventOrder(
+ "summer-gala", "ord_1042", Map.of("amountMinor", 500), "refund-ord_1042");
+
+seatlayer.holders().createHolderTransfer("holder-1042", Map.of(
+ "ticketIds", List.of("tkt_1"),
+ "toEmail", "friend@example.com"), null);
+```
+
+Request bodies are maps in the API's own field names. To send an explicit
+`null`, such as clearing a booking fee, use a map that allows null values
+(`LinkedHashMap`). The three CSV exports (`seasons().exportSeasonHoldersCsv`,
+`seasons().exportSeasonOrdersCsv`, `orders().exportEventOrdersCsv`) return the
+CSV text as a `String`. `seasons().deleteSeasonPlan` and
+`events().deleteEventDiscountCode` return nothing: the API answers 204.
+
## Test vs live
Keys carry their own mode. `sk_test_…` keys can only touch test-mode events and `sk_live_…` only
@@ -224,6 +324,8 @@ exactly when you don't want that, and you can control it explicitly:
seatlayer.events().list(EventListOptions.builder().limit(50).counts(false).build());
```
+Add `.seriesKey("ser_1")` to list only the dates of one event series.
+
## Keeping a hold alive
When an order takes longer than the checkout window (an invoice, a phone sale), extend rather than
@@ -315,17 +417,32 @@ support requests. All are unchecked, so they do not force `throws` clauses throu
## Reliability
**Retries and idempotency.** Reads (`GET`/`HEAD`) retry connection failures, 408, 429 and 5xx with
-exponential backoff and full jitter; `Retry-After` wins when the server sends it. Fourteen mutations
-use exact header replay: `charts().create`, `charts().copy`,
-`templates().instantiateTemplate`, `events().create`, `workspaces().create`,
-`performanceGroups().create`, `seasons().createSeason`, `seasons().updateSeason`,
-`seasons().deleteSeason`, `seasons().createSeasonPlan`, `seasons().duplicateSeasonToLive`,
-`seasons().createSeasonHolderImport`, `seasons().createSeasonRenewalOffers`, and
-`seasons().createSeasonAmendment`. They generate an `Idempotency-Key` when absent and reuse that key
-across every attempt. Overloads that accept a key let you provide a stable provisioning key instead.
+exponential backoff and full jitter; `Retry-After` wins when the server sends it. Forty-one
+mutations use exact header replay:
+
+- `charts().create`, `charts().copy`, `templates().instantiateTemplate`, `events().create`,
+ `workspaces().create`, and `performanceGroups().create`
+- 26 on `seasons()`: `createSeason`, `updateSeason`, `deleteSeason`, `createSeasonPlan`,
+ `updateSeasonPlan`, `deleteSeasonPlan`, `publishSeason`, `duplicateSeasonToLive`,
+ `createSeasonHolderImport`, `createSeasonHolderImportFromSeason`, `createSeasonRenewalOffers`,
+ `createSeasonAmendment`, `createSeasonPerformances`, `attachSeasonPerformances`,
+ `deleteSeasonPerformance`, `markSeasonPerformancePast`, `createSeasonCheckoutTest`,
+ `replaceSeasonPackagePrices`, `attachSeasonPlanPerformance`, `deleteSeasonPlanPerformance`,
+ `refundSeasonOrder`, `cancelSeasonOrder`, `cancelSeasonOrderDate`, `refundSeasonPerformance`,
+ `releaseSeasonLapsedOffers`, and `createSeasonRenewalCheckout`
+- `holders().updateHolder`, `holders().createHolderTransfer`, `holders().createHolderReturn`,
+ `holders().createHolderRenewalCheckout`, `orders().refundEventOrder`, and
+ `orders().cancelEventOrder`
+- `eventSeries().createEventSeries`, `eventSeries().addEventSeriesDates`, and
+ `eventSeries().updateEventSeries`
+
+They generate an `Idempotency-Key` when absent and reuse that key across every attempt. Overloads
+that accept a key let you provide a stable provisioning key instead; pass `null` to have one
+generated.
All remaining SDK mutations are single-attempt: holds, bookings, lifecycle changes, channel
-changes, show-once secret creation, and raw requests. Some have a server-side domain idempotency
+changes, show-once secret creation, ticket and renewal emails, renewal links, discount codes,
+event checkout, gateway, fee and sales changes, and raw requests. Some have a server-side domain idempotency
contract, but the SDK does not retry them automatically. Reconcile bookings with their required
`bookingRef`; never retry an unknown booking outcome as though the transport had made it safe.
@@ -356,14 +473,17 @@ outbox, and support operations.
| --- | --- |
| `charts()` | `list` `listAll` `create` `retrieve` `update` `delete` `copy` `archive` `unarchive` `publish` |
| `templates()` | `instantiateTemplate` |
-| `events()` | `list` `listAll` `create` `retrieve` `retrieveConfigurationBinding` `updateConfigurationBinding` `update` `delete` `updateChart` `close` `reopen` `archive` `retrieveHoldTtl` `updateHoldTtl` `listTicketReleases` `updateTicketReleases` `closeTicketRelease` `retrieveReport` `retrieveLog` |
+| `events()` | `list` `listAll` `create` `retrieve` `retrieveConfigurationBinding` `updateConfigurationBinding` `update` `delete` `updateChart` `close` `reopen` `archive` `retrieveHoldTtl` `updateHoldTtl` `listTicketReleases` `updateTicketReleases` `closeTicketRelease` `retrieveReport` `retrieveLog` `retrieveEventBuyerCheckout` `replaceEventBuyerCheckout` `retrieveEventPaymentGateway` `replaceEventPaymentGateway` `retrieveEventSalesReadiness` `preflightEventSales` `transitionEventSales` `retrieveEventBookingFee` `replaceEventBookingFee` `listEventDiscountCodes` `createEventDiscountCode` `updateEventDiscountCode` `endEventDiscountCode` `deleteEventDiscountCode` |
+| `eventSeries()` | `createEventSeries` `listEventSeries` `retrieveEventSeries` `addEventSeriesDates` `updateEventSeries` |
+| `orders()` | `listOrders` `retrieveOrder` `listOrderTickets` `listEventOrders` `retrieveEventOrder` `exportEventOrdersCsv` `refundEventOrder` `cancelEventOrder` `resendEventOrderTickets` |
+| `holders()` | `listCustomers` `retrieveHolder` `updateHolder` `revokeHolderSessions` `listHolderSeasons` `listHolderTickets` `retrieveHolderTicket` `createHolderTransfer` `listHolderTransfers` `cancelHolderTransfer` `acceptHolderTransfer` `createHolderReturn` `createHolderRenewalCheckout` `declineHolderRenewalOffer` |
| `channels()` | `list` `create` `update` `updateAssignments` `listAllocation` `retrieveAccessPreview` `retrieveReport` `pause` `unpause` `archive` `createBuyerAccessSession` `listBuyerAccessSessions` `revokeBuyerAccessSession` |
| `inventory()` | `hold` `holdBestAvailable` `bookBestAvailable` `extendHold` `retrieveHold` `release` `book` `bookLabels` `boxOfficeBook` `unbook` `block` `unblock` `unblockAll` `retrieveAvailability` `updateAvailability` `listBookings` `retrieveBooking` |
| `sessions()` | `createManageSession` `revokeManageSession` `createDesignerSession` `revokeDesignerSession` |
| `webhooks()` | `list` `create` `update` `delete` `listDeliveries` |
| `workspaces()` | `list` `create` `retrieve` `update` |
| `performanceGroups()` | `list` `create` `retrieve` `delete` `activate` `close` `retrieveLifecycle` `createBuyerAccessSession` `listBuyerAccessSessions` `revokeBuyerAccessSession` `retrieveHold` `bookHold` `retrieveBooking` |
-| `seasons()` | 48 operations for catalogue and Plan lifecycle, sales windows, buyer access and booking, holder imports, renewals, occurrence amendments, reports, audit, outbox, and support export |
+| `seasons()` | 87 operations for catalogue and Plan lifecycle, performances, package prices, sales windows, checkout tests, buyer access and booking, holders and holder imports, Season orders, renewals, hosted renewals and renewal checkouts, occurrence returns and amendments, bulk refunds, lapsed offer releases and jobs, reports and CSV exports, audit, outbox, and support export |
Full reference: [SeatLayer Java server SDK guide](https://docs.seatlayer.io/server-sdk/java/)
diff --git a/pom.xml b/pom.xml
index da7ecae..2b1d988 100644
--- a/pom.xml
+++ b/pom.xml
@@ -6,7 +6,7 @@
io.seatlayer
seatlayer-java
- 0.8.0
+ 0.9.0
jar
SeatLayer Java Seat Booking and Reserved Seating SDK
diff --git a/src/main/java/io/seatlayer/EventListOptions.java b/src/main/java/io/seatlayer/EventListOptions.java
index 6976ee5..ce2d8e3 100644
--- a/src/main/java/io/seatlayer/EventListOptions.java
+++ b/src/main/java/io/seatlayer/EventListOptions.java
@@ -1,15 +1,39 @@
package io.seatlayer;
-/** Filters and paging for {@link Events#list}. */
+/**
+ * Filters and paging for {@link Events#list}.
+ *
+ * @param workspaceId the workspace to list, or {@code null} for the caller's
+ * @param externalRef only the event with this caller-owned reference, or {@code null}
+ * @param limit the page size, or {@code null} for the default
+ * @param cursor the cursor from the previous page, or {@code null} to start
+ * @param counts whether to include live availability counts
+ * @param seriesKey only the dates of this event series, or {@code null}
+ */
public record EventListOptions(
- String workspaceId, String externalRef, Integer limit, String cursor, boolean counts) {
+ String workspaceId, String externalRef, Integer limit, String cursor, boolean counts,
+ String seriesKey) {
+
+ /**
+ * The options without a series filter, as before {@code seriesKey} was added.
+ *
+ * @param workspaceId the workspace to list, or {@code null} for the caller's
+ * @param externalRef only the event with this caller-owned reference, or {@code null}
+ * @param limit the page size, or {@code null} for the default
+ * @param cursor the cursor from the previous page, or {@code null} to start
+ * @param counts whether to include live availability counts
+ */
+ public EventListOptions(
+ String workspaceId, String externalRef, Integer limit, String cursor, boolean counts) {
+ this(workspaceId, externalRef, limit, cursor, counts, null);
+ }
public static Builder builder() {
return new Builder();
}
EventListOptions withCursor(String next) {
- return new EventListOptions(workspaceId, externalRef, limit, next, counts);
+ return new EventListOptions(workspaceId, externalRef, limit, next, counts, seriesKey);
}
public static final class Builder {
@@ -19,6 +43,7 @@ public static final class Builder {
private String cursor;
// Most callers of a single page want counts; listAll flips this off.
private boolean counts = true;
+ private String seriesKey;
public Builder workspaceId(String value) {
this.workspaceId = value;
@@ -47,8 +72,19 @@ public Builder counts(boolean value) {
return this;
}
+ /**
+ * Lists only the dates of one event series.
+ *
+ * @param value the event series key
+ * @return this builder
+ */
+ public Builder seriesKey(String value) {
+ this.seriesKey = value;
+ return this;
+ }
+
public EventListOptions build() {
- return new EventListOptions(workspaceId, externalRef, limit, cursor, counts);
+ return new EventListOptions(workspaceId, externalRef, limit, cursor, counts, seriesKey);
}
}
}
diff --git a/src/main/java/io/seatlayer/EventSeries.java b/src/main/java/io/seatlayer/EventSeries.java
new file mode 100644
index 0000000..a4dc896
--- /dev/null
+++ b/src/main/java/io/seatlayer/EventSeries.java
@@ -0,0 +1,117 @@
+package io.seatlayer;
+
+import static io.seatlayer.SeatLayerHttpClient.body;
+import static io.seatlayer.SeatLayerHttpClient.encode;
+
+import java.util.Map;
+
+/**
+ * Event series: many dated events planned from one schedule and changed together.
+ *
+ * A series is addressed by its SeatLayer event key.
+ */
+public final class EventSeries {
+
+ private final SeatLayerHttpClient http;
+
+ EventSeries(SeatLayerHttpClient http) {
+ this.http = http;
+ }
+
+ private static String path(String eventKey, String suffix) {
+ return "/v1/event-series/" + encode(eventKey) + suffix;
+ }
+
+ /**
+ * Plans an event series from a schedule, or makes it as a job.
+ *
+ *
Header replay: the same idempotency key is reused on every retry. The API answers
+ * 202 when the dates are made as a job. A series from an event that never started and was
+ * given up answers {@code 409 create_abandoned} for that key every time: send the request
+ * again with a new idempotency key.
+ *
+ *
Every date carries the series name as its name. Give {@code name} and {@code chartKey},
+ * or {@code fromEventKey}: an event you already set up becomes the first date under its own
+ * key, and every other date is a copy of it (floor plan, prices, checkout, poster and its own
+ * seat blocks, none of its orders, holds or sales). The series takes the event's name, zone
+ * and floor plan.
+ *
+ * @param params the request body: {@code name}, {@code chartKey} and {@code schedule}, or
+ * {@code fromEventKey} and {@code schedule}, plus any optional fields such as {@code dryRun}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map createEventSeries(Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay("/v1/event-series", params, idempotencyKey);
+ }
+
+ /**
+ * Lists the first page of event series.
+ *
+ * @return the decoded response
+ */
+ public Map listEventSeries() {
+ return listEventSeries(null, null);
+ }
+
+ /**
+ * Lists event series. Null arguments are not sent.
+ *
+ * @param limit the page size, or {@code null} for the server default
+ * @param cursor the cursor from the previous page, or {@code null}
+ * @return the decoded response
+ */
+ public Map listEventSeries(Integer limit, String cursor) {
+ return http.get("/v1/event-series", body("limit", limit, "cursor", cursor));
+ }
+
+ /**
+ * Retrieves an event series, its dates and its job.
+ *
+ * @param eventKey the series' event key
+ * @return the decoded response
+ */
+ public Map retrieveEventSeries(String eventKey) {
+ return http.get(path(eventKey, ""));
+ }
+
+ /**
+ * Adds dates to an event series, copied from its first date.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param eventKey the series' event key
+ * @param params the request body: one of {@code schedule}, {@code dates}, or
+ * {@code retryFailed: true} to make again every date that failed to be made (up to 100;
+ * {@code 422 nothing_to_retry} when none did, {@code 409 series_busy} while another change
+ * runs)
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map addEventSeriesDates(
+ String eventKey, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(path(eventKey, "/dates"), params, idempotencyKey);
+ }
+
+ /**
+ * Changes the name, prices or sales of every upcoming date in the series.
+ *
+ * {@code prices} takes {@code categories}: only the categories whose price changes (for a
+ * tiered category, only the tiers sent). Every price left out keeps each date's own value.
+ *
+ *
{@code sales: "on"} never opens a date its season cancelled: that date is a failed item
+ * of the job ({@code season_date_cancelled}), counted in the job's {@code failed} but not in
+ * {@code failedDates}, which are the dates that could not be made.
+ *
+ *
Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param eventKey the series' event key
+ * @param params the request body: any of {@code name}, {@code prices} and {@code sales}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map updateEventSeries(
+ String eventKey, Map params, String idempotencyKey) {
+ return http.mutationWithHeaderReplay("PATCH", path(eventKey, ""), params, idempotencyKey);
+ }
+}
diff --git a/src/main/java/io/seatlayer/Events.java b/src/main/java/io/seatlayer/Events.java
index d0fde29..45c40dd 100644
--- a/src/main/java/io/seatlayer/Events.java
+++ b/src/main/java/io/seatlayer/Events.java
@@ -32,6 +32,7 @@ public Page> list(EventListOptions options) {
if (!options.counts()) {
query.put("counts", "0");
}
+ query.put("seriesKey", options.seriesKey());
return Page.of(http.get("/v1/events", query), "events");
}
@@ -137,6 +138,13 @@ public Map close(String eventKey) {
return http.post("/v1/events/" + encode(eventKey) + "/close");
}
+ /**
+ * Opens a paused event's sales again. A date its season cancelled never opens again:
+ * {@code 409 season_date_cancelled}.
+ *
+ * @param eventKey the event key
+ * @return the decoded response
+ */
public Map reopen(String eventKey) {
return http.post("/v1/events/" + encode(eventKey) + "/reopen");
}
@@ -193,4 +201,206 @@ public Map retrieveLog(String eventKey, Integer limit, Long befo
"/v1/events/" + encode(eventKey) + "/log",
body("limit", limit, "before", before));
}
+
+ /**
+ * Retrieves who takes payment for the event, and what blocks a change.
+ *
+ * @param eventKey the event key
+ * @return the decoded response
+ */
+ public Map retrieveEventBuyerCheckout(String eventKey) {
+ return http.get("/v1/events/" + encode(eventKey) + "/buyer-checkout");
+ }
+
+ /**
+ * Chooses SeatLayer checkout or your own checkout for the event.
+ *
+ * Single attempt; the {@code expectedRevision} compare-and-set makes a repeat safe to
+ * reconcile.
+ *
+ * @param eventKey the event key
+ * @param params the request body: {@code buyerCheckout} and {@code expectedRevision}
+ * @return the decoded response
+ */
+ public Map replaceEventBuyerCheckout(String eventKey, Map params) {
+ return http.put("/v1/events/" + encode(eventKey) + "/buyer-checkout", params);
+ }
+
+ /**
+ * Retrieves the event's payment gateway and the gateways it could use.
+ *
+ * @param eventKey the event key
+ * @return the decoded response
+ */
+ public Map retrieveEventPaymentGateway(String eventKey) {
+ return retrieveEventPaymentGateway(eventKey, null);
+ }
+
+ /**
+ * Retrieves the event's payment gateway and the gateways it could use.
+ *
+ * @param eventKey the event key
+ * @param currency check the options against this currency instead of the event's, or
+ * {@code null}
+ * @return the decoded response
+ */
+ public Map retrieveEventPaymentGateway(String eventKey, String currency) {
+ return http.get(
+ "/v1/events/" + encode(eventKey) + "/payment-gateway", body("currency", currency));
+ }
+
+ /**
+ * Replaces the event's payment gateway, sending no request body.
+ *
+ * Single attempt, never retried automatically.
+ *
+ * @param eventKey the event key
+ * @return the decoded response
+ */
+ public Map replaceEventPaymentGateway(String eventKey) {
+ return replaceEventPaymentGateway(eventKey, null);
+ }
+
+ /**
+ * Assigns one of the organization's connected payment gateways to the event.
+ *
+ * Single attempt, never retried automatically.
+ *
+ * @param eventKey the event key
+ * @param params the optional request body ({@code connectionId}, {@code provider}), or
+ * {@code null}
+ * @return the decoded response
+ */
+ public Map replaceEventPaymentGateway(String eventKey, Map params) {
+ return http.put("/v1/events/" + encode(eventKey) + "/payment-gateway", params);
+ }
+
+ /**
+ * Retrieves what the event still needs before its next sales step.
+ *
+ * @param eventKey the event key
+ * @return the decoded response
+ */
+ public Map retrieveEventSalesReadiness(String eventKey) {
+ return http.get("/v1/events/" + encode(eventKey) + "/sales/readiness");
+ }
+
+ /**
+ * Records a test order as the event's sales preflight.
+ *
+ * Single attempt, never retried automatically.
+ *
+ * @param eventKey the event key
+ * @param params the request body: {@code orderId}
+ * @return the decoded response
+ */
+ public Map preflightEventSales(String eventKey, Map params) {
+ return http.post("/v1/events/" + encode(eventKey) + "/sales/preflight", params);
+ }
+
+ /**
+ * Moves the event's sales to testable, live, paused or ended. A date its season cancelled
+ * never opens again: moving it to {@code testable} or {@code live} answers
+ * {@code 409 season_date_cancelled}.
+ *
+ * Single attempt; the {@code expectedRevision} compare-and-set makes a repeat safe to
+ * reconcile.
+ *
+ * @param eventKey the event key
+ * @param params the request body: {@code to} and {@code expectedRevision}, and optionally
+ * {@code reason}
+ * @return the decoded response
+ */
+ public Map transitionEventSales(String eventKey, Map params) {
+ return http.post("/v1/events/" + encode(eventKey) + "/sales/transition", params);
+ }
+
+ /**
+ * Retrieves the event's booking fee.
+ *
+ * @param eventKey the event key
+ * @return the decoded response
+ */
+ public Map retrieveEventBookingFee(String eventKey) {
+ return http.get("/v1/events/" + encode(eventKey) + "/booking-fee");
+ }
+
+ /**
+ * Sets or clears the event's booking fee.
+ *
+ * Single attempt, never retried automatically. To clear the fee, send
+ * {@code bookingFeeMinor} as {@code null} in a map that allows null values.
+ *
+ * @param eventKey the event key
+ * @param params the request body: {@code bookingFeeMinor}
+ * @return the decoded response
+ */
+ public Map replaceEventBookingFee(String eventKey, Map params) {
+ return http.put("/v1/events/" + encode(eventKey) + "/booking-fee", params);
+ }
+
+ /**
+ * Lists the event's discount codes.
+ *
+ * @param eventKey the event key
+ * @return the decoded response
+ */
+ public Map listEventDiscountCodes(String eventKey) {
+ return http.get("/v1/events/" + encode(eventKey) + "/discount-codes");
+ }
+
+ /**
+ * Creates a discount code for the event.
+ *
+ * Single attempt, never retried automatically.
+ *
+ * @param eventKey the event key
+ * @param params the request body: {@code code} and {@code kind}, plus any optional fields
+ * @return the decoded response
+ */
+ public Map createEventDiscountCode(String eventKey, Map params) {
+ return http.post("/v1/events/" + encode(eventKey) + "/discount-codes", params);
+ }
+
+ /**
+ * Changes or pauses a discount code.
+ *
+ * Single attempt, never retried automatically.
+ *
+ * @param eventKey the event key
+ * @param codeId the discount code id
+ * @param params the request body: the fields to change
+ * @return the decoded response
+ */
+ public Map updateEventDiscountCode(
+ String eventKey, String codeId, Map params) {
+ return http.patch(
+ "/v1/events/" + encode(eventKey) + "/discount-codes/" + encode(codeId), params);
+ }
+
+ /**
+ * Ends a discount code for good.
+ *
+ * Single attempt; ending an ended code again has the same result.
+ *
+ * @param eventKey the event key
+ * @param codeId the discount code id
+ * @return the decoded response
+ */
+ public Map endEventDiscountCode(String eventKey, String codeId) {
+ return http.post(
+ "/v1/events/" + encode(eventKey) + "/discount-codes/" + encode(codeId) + "/end");
+ }
+
+ /**
+ * Deletes a discount code nobody has used. The API answers 204 No Content.
+ *
+ * Single attempt, never retried automatically.
+ *
+ * @param eventKey the event key
+ * @param codeId the discount code id
+ */
+ public void deleteEventDiscountCode(String eventKey, String codeId) {
+ http.delete("/v1/events/" + encode(eventKey) + "/discount-codes/" + encode(codeId));
+ }
}
diff --git a/src/main/java/io/seatlayer/Holders.java b/src/main/java/io/seatlayer/Holders.java
new file mode 100644
index 0000000..4d743c1
--- /dev/null
+++ b/src/main/java/io/seatlayer/Holders.java
@@ -0,0 +1,271 @@
+package io.seatlayer;
+
+import static io.seatlayer.SeatLayerHttpClient.body;
+import static io.seatlayer.SeatLayerHttpClient.encode;
+
+import java.util.Map;
+
+/**
+ * Season ticket holders: their customer record, sign-in sessions, seasons, tickets, ticket
+ * transfers, returns and renewals, plus the customer list.
+ *
+ *
A holder is addressed by the holder reference its imports and bookings carry.
+ */
+public final class Holders {
+
+ private final SeatLayerHttpClient http;
+
+ Holders(SeatLayerHttpClient http) {
+ this.http = http;
+ }
+
+ private static String path(String holderRef, String suffix) {
+ return "/v1/holders/" + encode(holderRef) + suffix;
+ }
+
+ /**
+ * Lists the first page of customers.
+ *
+ * @return the decoded response
+ */
+ public Map listCustomers() {
+ return listCustomers(null, null, null, null);
+ }
+
+ /**
+ * Lists or finds customers by email or holder reference. Null filters are not sent.
+ *
+ * @param email only the customer with this email, or {@code null}
+ * @param holderRef only the customer linked to this holder reference, or {@code null}
+ * @param cursor the cursor from the previous page, or {@code null}
+ * @param limit the page size, or {@code null} for the server default
+ * @return the decoded response
+ */
+ public Map listCustomers(
+ String email, String holderRef, String cursor, Integer limit) {
+ return http.get(
+ "/v1/customers",
+ body("email", email, "holderRef", holderRef, "cursor", cursor, "limit", limit));
+ }
+
+ /**
+ * Retrieves the customer behind a holder reference.
+ *
+ * @param holderRef the holder reference
+ * @return the decoded response
+ */
+ public Map retrieveHolder(String holderRef) {
+ return http.get(path(holderRef, ""));
+ }
+
+ /**
+ * Sets a holder's email, name or phone.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param holderRef the holder reference
+ * @param params the request body: any of {@code email}, {@code name} and {@code phone}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map updateHolder(
+ String holderRef, Map params, String idempotencyKey) {
+ return http.mutationWithHeaderReplay("PATCH", path(holderRef, ""), params, idempotencyKey);
+ }
+
+ /**
+ * Signs the holder's customer out of the ticket site everywhere.
+ *
+ * @param holderRef the holder reference
+ * @return the decoded response
+ */
+ public Map revokeHolderSessions(String holderRef) {
+ return revokeHolderSessions(holderRef, null);
+ }
+
+ /**
+ * Signs the holder's customer out of the ticket site.
+ *
+ * Single attempt; signing out twice has the same result as once.
+ *
+ * @param holderRef the holder reference
+ * @param params the optional request body ({@code sessionId} for one session), or
+ * {@code null} for every session
+ * @return the decoded response
+ */
+ public Map revokeHolderSessions(String holderRef, Map params) {
+ return http.post(path(holderRef, "/sessions/revoke"), params);
+ }
+
+ /**
+ * Lists the seasons a holder holds seats in.
+ *
+ * @param holderRef the holder reference
+ * @return the decoded response
+ */
+ public Map listHolderSeasons(String holderRef) {
+ return http.get(path(holderRef, "/seasons"));
+ }
+
+ /**
+ * Lists the first page of a holder's tickets, date by date.
+ *
+ * @param holderRef the holder reference
+ * @return the decoded response
+ */
+ public Map listHolderTickets(String holderRef) {
+ return listHolderTickets(holderRef, null, null, null, null, null);
+ }
+
+ /**
+ * Lists a holder's tickets, date by date. Null filters are not sent.
+ *
+ * @param holderRef the holder reference
+ * @param seasonKey only tickets of this Season, or {@code null}
+ * @param from only dates starting at or after this time, in epoch milliseconds, or {@code null}
+ * @param to only dates starting before this time, in epoch milliseconds, or {@code null}
+ * @param cursor the cursor from the previous page, or {@code null}
+ * @param limit the page size, or {@code null} for the server default
+ * @return the decoded response
+ */
+ public Map listHolderTickets(
+ String holderRef, String seasonKey, Long from, Long to, String cursor, Integer limit) {
+ return http.get(
+ path(holderRef, "/tickets"),
+ body(
+ "seasonKey", seasonKey,
+ "from", from,
+ "to", to,
+ "cursor", cursor,
+ "limit", limit));
+ }
+
+ /**
+ * Retrieves one of a holder's tickets with its QR.
+ *
+ * @param holderRef the holder reference
+ * @param ticketId the ticket id
+ * @return the decoded response
+ */
+ public Map retrieveHolderTicket(String holderRef, String ticketId) {
+ return http.get(path(holderRef, "/tickets/" + encode(ticketId)));
+ }
+
+ /**
+ * Sends some of a holder's season tickets to an email. Turning customer sends off in Settings ›
+ * Ticket site doesn't stop your server; cut-offs still apply.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param holderRef the holder reference
+ * @param params the request body: {@code ticketIds} and {@code toEmail}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map createHolderTransfer(
+ String holderRef, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(path(holderRef, "/transfers"), params, idempotencyKey);
+ }
+
+ /**
+ * Lists the transfers a holder sent or was sent.
+ *
+ * @param holderRef the holder reference
+ * @return the decoded response
+ */
+ public Map listHolderTransfers(String holderRef) {
+ return http.get(path(holderRef, "/transfers"));
+ }
+
+ /**
+ * Cancels a transfer that has not been accepted.
+ *
+ * Single attempt; the server applies a repeat exactly once.
+ *
+ * @param holderRef the sending holder's reference
+ * @param transferId the transfer id
+ * @return the decoded response
+ */
+ public Map cancelHolderTransfer(String holderRef, String transferId) {
+ return http.post(path(holderRef, "/transfers/" + encode(transferId) + "/cancel"));
+ }
+
+ /**
+ * Accepts a transfer for the recipient holder.
+ *
+ * Single attempt; the server applies a repeat exactly once.
+ *
+ * @param holderRef the recipient holder's reference
+ * @param transferId the transfer id
+ * @return the decoded response
+ */
+ public Map acceptHolderTransfer(String holderRef, String transferId) {
+ return http.post(path(holderRef, "/transfers/" + encode(transferId) + "/accept"));
+ }
+
+ /**
+ * Gives back a holder's seat on one date, one per ticket. Turning give-backs off in Settings ›
+ * Ticket site doesn't stop your server; cut-offs still apply.
+ *
+ * Header replay: the same idempotency key is reused on every retry. A repeat answers with
+ * the same return.
+ *
+ * @param holderRef the holder reference
+ * @param params the request body: {@code ticketIds}, 1 to 20 tickets of one season
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response, with the return under {@code return}
+ */
+ public Map createHolderReturn(
+ String holderRef, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(path(holderRef, "/returns"), params, idempotencyKey);
+ }
+
+ /**
+ * Starts a SeatLayer checkout that renews one of a holder's offers ({@code renewalOffer} on
+ * {@link #listHolderSeasons(String)}). Send the buyer to {@code payment.url}.
+ *
+ * Header replay: the same idempotency key is reused on every retry and answers the same
+ * order.
+ *
+ * @param holderRef the holder reference
+ * @param offerId the renewal offer id
+ * @param params the request body: {@code returnUrl} (on one of the organization's allowed
+ * domains), plus optional {@code buyerEmail}, {@code buyerName} and {@code provider}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map createHolderRenewalCheckout(
+ String holderRef, String offerId, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ path(holderRef, "/renewal-offers/" + encode(offerId) + "/checkout"), params, idempotencyKey);
+ }
+
+ /**
+ * Declines one of a holder's renewal offers and releases its seats, with no reason.
+ *
+ * Single attempt; declining again answers the same offer.
+ *
+ * @param holderRef the holder reference
+ * @param offerId the renewal offer id
+ * @return the decoded response
+ */
+ public Map declineHolderRenewalOffer(String holderRef, String offerId) {
+ return declineHolderRenewalOffer(holderRef, offerId, null);
+ }
+
+ /**
+ * Declines one of a holder's renewal offers and releases its seats.
+ *
+ * Single attempt; declining again answers the same offer, with the first reason.
+ *
+ * @param holderRef the holder reference
+ * @param offerId the renewal offer id
+ * @param params the optional request body ({@code reason}, 1 to 200 characters, kept on the
+ * offer as {@code declineReason}), or {@code null} to send no body
+ * @return the decoded response
+ */
+ public Map declineHolderRenewalOffer(
+ String holderRef, String offerId, Map params) {
+ return http.post(path(holderRef, "/renewal-offers/" + encode(offerId) + "/decline"), params);
+ }
+}
diff --git a/src/main/java/io/seatlayer/Orders.java b/src/main/java/io/seatlayer/Orders.java
new file mode 100644
index 0000000..8dd2fad
--- /dev/null
+++ b/src/main/java/io/seatlayer/Orders.java
@@ -0,0 +1,277 @@
+package io.seatlayer;
+
+import static io.seatlayer.SeatLayerHttpClient.body;
+import static io.seatlayer.SeatLayerHttpClient.encode;
+
+import java.util.Map;
+
+/**
+ * Orders SeatLayer took: the order list across events and seasons, one event's orders,
+ * refunds, cancellations and ticket emails.
+ *
+ * Season order refunds and cancellations live on {@link Seasons}.
+ */
+public final class Orders {
+
+ private final SeatLayerHttpClient http;
+
+ Orders(SeatLayerHttpClient http) {
+ this.http = http;
+ }
+
+ /**
+ * Lists the first page of orders across events and seasons.
+ *
+ * @return the decoded response
+ */
+ public Map listOrders() {
+ return listOrders(null, null, null, null, null, null, null, null);
+ }
+
+ /**
+ * Lists orders across events and seasons. Null filters are not sent.
+ *
+ * @param eventKey only this event's orders, or {@code null}
+ * @param seasonKey only this Season's orders, renewals included, or {@code null}
+ * @param status only orders in this state, or {@code null}
+ * @param from created at or after this time, in epoch milliseconds, or {@code null}
+ * @param to created before this time, in epoch milliseconds, or {@code null}
+ * @param cursor the cursor from the previous page, or {@code null}
+ * @param limit the page size, or {@code null} for the server default
+ * @return the decoded response
+ */
+ public Map listOrders(
+ String eventKey,
+ String seasonKey,
+ String status,
+ Long from,
+ Long to,
+ String cursor,
+ Integer limit) {
+ return listOrders(eventKey, seasonKey, null, status, from, to, cursor, limit);
+ }
+
+ /**
+ * Lists orders across events and seasons, optionally one holder's. Null filters are not sent.
+ * Each order carries {@code holderRef} and {@code customerId}; {@code buyer.email} is null for
+ * a box office sale taken without one.
+ *
+ * @param eventKey only this event's orders, or {@code null}
+ * @param seasonKey only this Season's orders, renewals included, or {@code null}
+ * @param holderRef only this holder's orders (the Season order with this id and renewals
+ * offered to this reference), or {@code null}
+ * @param status only orders in this state, or {@code null}
+ * @param from created at or after this time, in epoch milliseconds, or {@code null}
+ * @param to created before this time, in epoch milliseconds, or {@code null}
+ * @param cursor the cursor from the previous page, or {@code null}
+ * @param limit the page size, or {@code null} for the server default
+ * @return the decoded response
+ */
+ public Map listOrders(
+ String eventKey,
+ String seasonKey,
+ String holderRef,
+ String status,
+ Long from,
+ Long to,
+ String cursor,
+ Integer limit) {
+ return http.get(
+ "/v1/orders",
+ body(
+ "eventKey", eventKey,
+ "seasonKey", seasonKey,
+ "holderRef", holderRef,
+ "status", status,
+ "from", from,
+ "to", to,
+ "cursor", cursor,
+ "limit", limit));
+ }
+
+ /**
+ * Retrieves an order and its lines.
+ *
+ * @param orderId the order id
+ * @return the decoded response
+ */
+ public Map retrieveOrder(String orderId) {
+ return http.get("/v1/orders/" + encode(orderId));
+ }
+
+ /**
+ * Lists an order's tickets with their scan links.
+ *
+ * @param orderId the order id
+ * @return the decoded response
+ */
+ public Map listOrderTickets(String orderId) {
+ return http.get("/v1/orders/" + encode(orderId) + "/tickets");
+ }
+
+ /**
+ * Lists the first page of one event's orders.
+ *
+ * @param eventKey the event key
+ * @return the decoded response
+ */
+ public Map listEventOrders(String eventKey) {
+ return listEventOrders(eventKey, null, null, null, null, null, null, null);
+ }
+
+ /**
+ * Lists one event's orders. Null filters are not sent.
+ *
+ * @param eventKey the event key
+ * @param q search by buyer name, email, order number or seat, or {@code null}
+ * @param status only orders in this state, or {@code null}
+ * @param paidBy only orders paid this way, or {@code null}
+ * @param from paid at or after this time, in epoch milliseconds, or {@code null}
+ * @param to paid before this time, in epoch milliseconds, or {@code null}
+ * @param cursor the cursor from the previous page, or {@code null}
+ * @param limit the page size, or {@code null} for the server default
+ * @return the decoded response
+ */
+ public Map listEventOrders(
+ String eventKey,
+ String q,
+ String status,
+ String paidBy,
+ Long from,
+ Long to,
+ String cursor,
+ Integer limit) {
+ return http.get(
+ "/v1/events/" + encode(eventKey) + "/orders",
+ body(
+ "q", q,
+ "status", status,
+ "paidBy", paidBy,
+ "from", from,
+ "to", to,
+ "cursor", cursor,
+ "limit", limit));
+ }
+
+ /**
+ * Retrieves one event order with its guests and tickets.
+ *
+ * @param eventKey the event key
+ * @param orderId the order id
+ * @return the decoded response
+ */
+ public Map retrieveEventOrder(String eventKey, String orderId) {
+ return http.get("/v1/events/" + encode(eventKey) + "/orders/" + encode(orderId));
+ }
+
+ /**
+ * Downloads all of one event's orders as CSV.
+ *
+ * @param eventKey the event key
+ * @return the CSV text, exactly as the API sent it
+ */
+ public String exportEventOrdersCsv(String eventKey) {
+ return exportEventOrdersCsv(eventKey, null, null, null, null, null);
+ }
+
+ /**
+ * Downloads one event's matching orders as CSV. Null filters are not sent.
+ *
+ * @param eventKey the event key
+ * @param q search by buyer name, email, order number or seat, or {@code null}
+ * @param status only orders in this state, or {@code null}
+ * @param paidBy only orders paid this way, or {@code null}
+ * @param from paid at or after this time, in epoch milliseconds, or {@code null}
+ * @param to paid before this time, in epoch milliseconds, or {@code null}
+ * @return the CSV text, exactly as the API sent it
+ */
+ public String exportEventOrdersCsv(
+ String eventKey, String q, String status, String paidBy, Long from, Long to) {
+ return http.getText(
+ "/v1/events/" + encode(eventKey) + "/orders.csv",
+ body("q", q, "status", status, "paidBy", paidBy, "from", from, "to", to));
+ }
+
+ /**
+ * Refunds an event order in full through its payment provider.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param eventKey the event key
+ * @param orderId the order id
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map refundEventOrder(
+ String eventKey, String orderId, String idempotencyKey) {
+ return refundEventOrder(eventKey, orderId, null, idempotencyKey);
+ }
+
+ /**
+ * Refunds an event order in full or in part through its payment provider.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param eventKey the event key
+ * @param orderId the order id
+ * @param params the optional request body ({@code amountMinor}), or {@code null} for a full refund
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map refundEventOrder(
+ String eventKey, String orderId, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ "/v1/events/" + encode(eventKey) + "/orders/" + encode(orderId) + "/refund",
+ params,
+ idempotencyKey);
+ }
+
+ /**
+ * Cancels an event order without moving money.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param eventKey the event key
+ * @param orderId the order id
+ * @param params the request body: {@code reason}, plus any optional fields
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map cancelEventOrder(
+ String eventKey, String orderId, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ "/v1/events/" + encode(eventKey) + "/orders/" + encode(orderId) + "/cancel",
+ params,
+ idempotencyKey);
+ }
+
+ /**
+ * Emails an event order's tickets again, to the address on the order.
+ *
+ * Single attempt, never retried automatically.
+ *
+ * @param eventKey the event key
+ * @param orderId the order id
+ * @return the decoded response
+ */
+ public Map resendEventOrderTickets(String eventKey, String orderId) {
+ return resendEventOrderTickets(eventKey, orderId, null);
+ }
+
+ /**
+ * Emails an event order's tickets again.
+ *
+ * Single attempt, never retried automatically.
+ *
+ * @param eventKey the event key
+ * @param orderId the order id
+ * @param params the optional request body ({@code email}), or {@code null}
+ * @return the decoded response
+ */
+ public Map resendEventOrderTickets(
+ String eventKey, String orderId, Map params) {
+ return http.post(
+ "/v1/events/" + encode(eventKey) + "/orders/" + encode(orderId) + "/resend",
+ params);
+ }
+}
diff --git a/src/main/java/io/seatlayer/Seasons.java b/src/main/java/io/seatlayer/Seasons.java
index f448e11..bc0be68 100644
--- a/src/main/java/io/seatlayer/Seasons.java
+++ b/src/main/java/io/seatlayer/Seasons.java
@@ -4,6 +4,7 @@
import static io.seatlayer.SeatLayerHttpClient.encode;
import java.util.Map;
+import java.util.Objects;
/** Fixed Renewable Season organizer operations for trusted backends. */
public final class Seasons {
@@ -18,6 +19,56 @@ private static String path(String seasonKey, String suffix) {
return "/v1/seasons/" + encode(seasonKey) + suffix;
}
+ /**
+ * The job voiding a cancelled date's tickets: {@code sbj_void_} and the cancel's
+ * {@code amendmentId}. Cancelling a date starts it (a repeated cancel joins it); follow it with
+ * {@link #retrieveSeasonBulkJob}. Each Season ticket it voids is told by
+ * {@code season.ticket.voided} with reason {@code date_cancelled}.
+ *
+ * Not an API call: the cancel's answer does not name the job, so this names it.
+ *
+ * @param amendmentId the {@code amendmentId} of the {@code cancel} amendment
+ * @return the {@code date_cancel_void} job id
+ */
+ public static String dateCancelVoidJobId(String amendmentId) {
+ return "sbj_void_" + Objects.requireNonNull(amendmentId, "amendmentId");
+ }
+
+ /**
+ * The most rows one {@link #createSeasonHolderImport} call takes for a package of
+ * {@code dates} dates. Each row is fenced on every date: 100 up to 20 dates, then
+ * {@code floor(2300 / (dates + 3))}, 43 at 50. A call with more answers
+ * {@code 422 invalid_rows} with {@code maxRows}.
+ *
+ *
Not an API call.
+ *
+ * @param dates the number of dates in the package (2 to 50)
+ * @return the most rows one import call takes, at least 1
+ */
+ public static int holderImportRowsPerCall(int dates) {
+ long perCall = 2300L / (Math.max(1, dates) + 3L);
+ return (int) Math.max(1, Math.min(100, perCall));
+ }
+
+ /**
+ * Whether an answer is the {@code 202} a season-seats season's date cancel
+ * ({@link #createSeasonAmendment}) or past date ({@link #markSeasonPerformancePast}) sends
+ * while the date is still leaving every season seat: {@code state} {@code finishing},
+ * {@code code} {@code block_date_leave_pending}, with {@code eventKey}, {@code shardsLeft}
+ * and {@code shardCount}. It finishes by itself: send the same request again after
+ * {@code Retry-After} to read how it ended.
+ *
+ *
Not an API call.
+ *
+ * @param answer a decoded response, or {@code null}
+ * @return true for the date-leave {@code 202}
+ */
+ public static boolean isDateLeavePending(Map answer) {
+ return answer != null
+ && "finishing".equals(answer.get("state"))
+ && "block_date_leave_pending".equals(answer.get("code"));
+ }
+
public Map listSeasons() {
return http.get("/v1/seasons");
}
@@ -42,6 +93,24 @@ public Map createSeason(Map params) {
return createSeason(params, null);
}
+ /**
+ * Creates a draft Season.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ *
Every Season answer carries {@code inventoryMode}: how the season's seats are decided,
+ * {@code block} once season seats are turned on for it ({@code inventoryMode: "block"} on
+ * create or update) or it sells from its block, else {@code per_hold}.
+ *
+ * @param params the request body: {@code name}, {@code eventKeys} or
+ * {@code sourcePerformanceGroupKeys}, and optionally {@code edition}, {@code mode},
+ * {@code singleTickets} ({@code true}: each date also sells its own single tickets once
+ * the Season is on sale; the default {@code false} is Season only) and
+ * {@code inventoryMode} ({@code block} turns season seats on for this Season; the default
+ * is {@code per_hold}, and anything else answers {@code 422 invalid_inventory_mode})
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
public Map createSeason(Map params, String idempotencyKey) {
return http.postWithHeaderReplay("/v1/seasons", params, idempotencyKey);
}
@@ -50,6 +119,35 @@ public Map retrieveSeason(String seasonKey) {
return http.get(path(seasonKey, ""));
}
+ /**
+ * Renames a draft Season, or sets how it sells.
+ *
+ * Header replay: the same idempotency key is reused on every retry. A retry with the first
+ * key and the same {@code expectedRevision} is not applied twice.
+ *
+ *
When a {@code season_singles} job could not start, {@code singleTicketDates} carries
+ * {@code jobRefused} saying why. The change still stands, and the dates wait in
+ * {@code singleTicketsNotOpen} until you send {@code singleTickets: true} again.
+ *
+ * @param seasonKey the Season key
+ * @param params the request body: {@code expectedRevision}, plus any of {@code name},
+ * {@code edition}, {@code checkoutMode} ({@code seatlayer} or {@code server}; it cannot go
+ * back to undecided and is fixed once a live booking exists), {@code transferCutoffHours}
+ * and {@code returnCutoffHours} (hours before a date starts, 0 to 720, or {@code null} for
+ * the club default in Settings › Ticket site, or until it starts when the club has none),
+ * {@code audience} ({@code embed_only} or {@code public}; an ended
+ * Season cannot become public, {@code 409 sales_ended}), {@code singleTickets} (turned
+ * on while the Season is on sale, each upcoming date's own sales open through its
+ * readiness checks; turned off, they stop), and {@code inventoryMode} ({@code block}
+ * turns season seats on for this Season; {@code per_hold} turns them off again, refused
+ * with {@code 409 season_block_exists} once seats are set aside; it does not change the
+ * Season's {@code revision}; refused with {@code 409 season_block_packages} (more than one
+ * package), {@code 409 season_block_on_sale} (sales already opened without season seats),
+ * {@code 409 season_not_draft_or_active}, or {@code 422 invalid_inventory_mode})
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response; a change to {@code singleTickets} names the dates it opened
+ * or stopped in {@code singleTicketDates}
+ */
public Map updateSeason(
String seasonKey, Map params, String idempotencyKey) {
return http.mutationWithHeaderReplay("PATCH", path(seasonKey, ""), params, idempotencyKey);
@@ -103,6 +201,17 @@ private Map sales(String seasonKey, String action, int expectedR
path(seasonKey, "/sales/" + action), body("expectedRevision", expectedRevision));
}
+ /**
+ * Opens sales. The answer's {@code warnings} say what is advised but not required, such as
+ * {@code checkout_test_missing} until a checkout test or rehearsal has passed. Refused with
+ * {@code 409 plan_not_published} or {@code 409 checkout_mode_not_chosen} until a package is
+ * published and a checkout mode is chosen, and with {@code 409 block_not_ready} when season
+ * seats are turned on ({@code inventoryMode} {@code block}) but the seats are not set aside yet.
+ *
+ * @param seasonKey the Season key
+ * @param expectedRevision the Season revision the caller last read
+ * @return the decoded response, with {@code season} and {@code warnings}
+ */
public Map openSeasonSales(String seasonKey, int expectedRevision) {
return sales(seasonKey, "open", expectedRevision);
}
@@ -139,6 +248,13 @@ public Map revokeSeasonBuyerAccessSession(String seasonKey, Stri
return http.delete(path(seasonKey, "/buyer-access-sessions/" + encode(sessionId)));
}
+ /**
+ * Retrieves a Season hold. Each seat carries the {@code priceTypeKey} it is held as.
+ *
+ * @param seasonKey the Season key
+ * @param operationId the hold operation id
+ * @return the decoded response
+ */
public Map retrieveSeasonHold(String seasonKey, String operationId) {
return http.get(path(seasonKey, "/holds/" + encode(operationId)));
}
@@ -174,6 +290,24 @@ public Map validateSeasonBuyerRehearsal(String seasonKey) {
return http.post(path(seasonKey, "/buyer-rehearsals/validate"));
}
+ /**
+ * Imports incumbent holders, as a dry run or for real.
+ *
+ * A package holds 2 to 50 dates. A call takes at most
+ * {@link #holderImportRowsPerCall(int)} rows for the package's dates (100 up to 20 dates, 43
+ * at 50); more is refused with {@code 422 invalid_rows}, and the error's {@code body()} carries
+ * {@code maxRows}.
+ *
+ *
Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param params the request body: {@code successorPlanActivationId}, {@code rows} and optionally
+ * {@code dryRun}; each row takes {@code rowId}, {@code holderRef},
+ * {@code priorPlanActivationId}, {@code priorContractRef} and {@code labels}, plus optional
+ * {@code existingBookingRef}, {@code holderEmail} and {@code holderName}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
public Map createSeasonHolderImport(
String seasonKey, Map params, String idempotencyKey) {
return http.postWithHeaderReplay(path(seasonKey, "/imports"), params, idempotencyKey);
@@ -183,16 +317,59 @@ public Map retrieveSeasonHolderImport(String seasonKey, String i
return http.get(path(seasonKey, "/imports/" + encode(importId)));
}
+ /**
+ * Makes one renewal offer per eligible prior Contract.
+ *
+ * For 100 contracts or fewer the offers are made in this call: {@code 201} with the
+ * {@code offers}. For more than 100, a {@code renewal_run} job makes them: {@code 202} with the
+ * {@code job} and its {@code batchId}. Follow the job with {@link #retrieveSeasonBulkJob},
+ * then read the offers with {@link #listSeasonRenewalOffers(String, String, Integer)}. Can
+ * refuse with {@code 409 job_mismatch} or {@code 503 season_not_configured}.
+ *
+ *
Header replay: the same idempotency key is reused on every retry and answers the same job.
+ *
+ * @param seasonKey the Season key
+ * @param params the request body: {@code deadlineAt}, and optionally
+ * {@code successorPlanActivationId} and {@code contractIds}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response: the {@code offers}, or the {@code job} and {@code batchId}
+ */
public Map createSeasonRenewalOffers(
String seasonKey, Map params, String idempotencyKey) {
return http.postWithHeaderReplay(
path(seasonKey, "/renewal-offers"), params, idempotencyKey);
}
+ /**
+ * Lists the first page of renewal offers, newest first.
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response, with the {@code offers} and {@code nextCursor}
+ */
public Map listSeasonRenewalOffers(String seasonKey) {
- return http.get(path(seasonKey, "/renewal-offers"));
+ return listSeasonRenewalOffers(seasonKey, null, null);
+ }
+
+ /**
+ * Lists renewal offers, one page at a time, newest first. Null arguments are not sent.
+ *
+ * @param seasonKey the Season key
+ * @param cursor the {@code nextCursor} from the previous page, or {@code null}
+ * @param limit offers a page, 1-100, or {@code null} for 100
+ * @return the decoded response, with the {@code offers} and {@code nextCursor} (null on the
+ * last page)
+ */
+ public Map listSeasonRenewalOffers(String seasonKey, String cursor, Integer limit) {
+ return http.get(path(seasonKey, "/renewal-offers"), body("cursor", cursor, "limit", limit));
}
+ /**
+ * Retrieves a renewal offer, with its {@code seats} and the {@code priceTypeKey} each renews at.
+ *
+ * @param seasonKey the Season key
+ * @param offerId the renewal offer id
+ * @return the decoded response
+ */
public Map retrieveSeasonRenewalOffer(String seasonKey, String offerId) {
return http.get(path(seasonKey, "/renewal-offers/" + encode(offerId)));
}
@@ -204,6 +381,13 @@ public Map extendSeasonRenewalOffer(
body("deadlineAt", deadlineAt));
}
+ /**
+ * Inspects a renewal offer, with its {@code seats} and the {@code priceTypeKey} each renews at.
+ *
+ * @param seasonKey the Season key
+ * @param offerId the renewal offer id
+ * @return the decoded response
+ */
public Map inspectSeasonRenewalOffer(String seasonKey, String offerId) {
return http.get(path(seasonKey, "/renewal-offers/" + encode(offerId) + "/inspect"));
}
@@ -224,9 +408,35 @@ public Map commitSeasonRenewalOffer(
"planActivationId", planActivationId));
}
+ /**
+ * Declines a renewal offer and releases its seats at once, with no reason.
+ *
+ * Single attempt; a repeated decline answers the same offer.
+ *
+ * @param seasonKey the Season key
+ * @param offerId the renewal offer id
+ * @return the decoded response
+ */
public Map declineSeasonRenewalOffer(String seasonKey, String offerId) {
+ return declineSeasonRenewalOffer(seasonKey, offerId, null);
+ }
+
+ /**
+ * Declines a renewal offer and releases its seats at once.
+ *
+ * Single attempt; a repeated decline answers the same offer and keeps the first reason.
+ *
+ * @param seasonKey the Season key
+ * @param offerId the renewal offer id
+ * @param params the optional request body ({@code reason}, 1 to 200 characters, kept on the
+ * offer as {@code declineReason}), or {@code null} for none
+ * @return the decoded response
+ */
+ public Map declineSeasonRenewalOffer(
+ String seasonKey, String offerId, Map params) {
return http.post(
- path(seasonKey, "/renewal-offers/" + encode(offerId) + "/decline"), Map.of());
+ path(seasonKey, "/renewal-offers/" + encode(offerId) + "/decline"),
+ params == null ? Map.of() : params);
}
public Map releaseSeasonRenewalOffer(String seasonKey, String offerId) {
@@ -238,6 +448,30 @@ public Map listSeasonOccurrences(String seasonKey) {
return http.get(path(seasonKey, "/occurrences"));
}
+ /**
+ * Amends one date of a published Season.
+ *
+ * A {@code cancel} also voids every live ticket for the date as a {@code date_cancel_void}
+ * job, {@link #dateCancelVoidJobId(String)} of the answer's {@code amendmentId}; follow it with
+ * {@link #retrieveSeasonBulkJob}. Each Season ticket it voids is told by
+ * {@code season.ticket.voided} with reason {@code date_cancelled}. A cancelled date can't be
+ * moved ({@code reschedule}), postponed or replaced: {@code 409 performance_cancelled}. On a
+ * season-seats season, a {@code cancel} first takes the date off every season seat: while
+ * that finishes the answer is a {@code 202} (check with {@link #isDateLeavePending}); send the
+ * same request again to read the amendment.
+ *
+ *
Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param params the request body: {@code eventKey} and {@code kind} ({@code reschedule},
+ * {@code replace}, {@code cancel_exception}, {@code postpone} or {@code cancel}), plus
+ * optional {@code startsAt}, {@code name}, {@code planActivationId}, and, with
+ * {@code cancel} only, {@code refund} ({@code none} or {@code per_date}, each order's
+ * share of the date; a whole-order refund is the order refund) and {@code reason}; a
+ * refunding cancel answers with its {@code refundJob}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
public Map createSeasonAmendment(
String seasonKey, Map params, String idempotencyKey) {
return http.postWithHeaderReplay(path(seasonKey, "/amendments"), params, idempotencyKey);
@@ -282,4 +516,748 @@ public Map listSeasonAudit(String seasonKey) {
public Map exportSeasonSupportSnapshot(String seasonKey) {
return http.get(path(seasonKey, "/export"));
}
+
+ /**
+ * Dry-runs or commits renewal rights derived from a previous Season's holders.
+ *
+ * A dry run answers {@code 200} and a commit of 100 holders or fewer {@code 201}, both with
+ * the {@code import}. A commit of more than 100 holders answers {@code 202} with the
+ * {@code job}: a {@code holder_import} job brings them across. Follow it with
+ * {@link #retrieveSeasonBulkJob}; its {@code summary} has the same counts when it completes.
+ * Can refuse with {@code 409 job_mismatch} or {@code 503 job_busy} or
+ * {@code season_not_configured}.
+ *
+ *
Header replay: the same idempotency key is reused on every retry and answers the same job.
+ *
+ * @param seasonKey the Season key
+ * @param params the request body: {@code sourceSeasonId} and {@code successorPlanActivationId},
+ * and optionally {@code dryRun}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response: the {@code import}, or the {@code job}
+ */
+ public Map createSeasonHolderImportFromSeason(
+ String seasonKey, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ path(seasonKey, "/imports/from-season"), params, idempotencyKey);
+ }
+
+ /**
+ * Lists the Season's performances and their package membership, in every lifecycle state.
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response
+ */
+ public Map listSeasonPerformances(String seasonKey) {
+ return http.get(path(seasonKey, "/performances"));
+ }
+
+ /**
+ * Creates performances inside a draft Season from a repeat rule.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param params the request body: {@code titlePattern}, {@code timezone} and {@code repeat},
+ * plus any optional fields
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map createSeasonPerformances(
+ String seasonKey, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(path(seasonKey, "/performances"), params, idempotencyKey);
+ }
+
+ /**
+ * Attaches existing Events to a draft Season and its packages.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param params the request body: {@code eventKeys}, and optionally {@code attachToPlanKeys}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map attachSeasonPerformances(
+ String seasonKey, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ path(seasonKey, "/performances/attach"), params, idempotencyKey);
+ }
+
+ /**
+ * Removes a performance from a draft Season and from every package.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param eventKey the performance's Event key
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map deleteSeasonPerformance(
+ String seasonKey, String eventKey, String idempotencyKey) {
+ return http.mutationWithHeaderReplay(
+ "DELETE", path(seasonKey, "/performances/" + encode(eventKey)), null, idempotencyKey);
+ }
+
+ /**
+ * Renames a draft package or changes the performances it covers.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param planKey the package (Plan) key
+ * @param params the request body: {@code name} and/or {@code eventKeys}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map updateSeasonPlan(
+ String seasonKey, String planKey, Map params, String idempotencyKey) {
+ return http.mutationWithHeaderReplay(
+ "PATCH", path(seasonKey, "/plans/" + encode(planKey)), params, idempotencyKey);
+ }
+
+ /**
+ * Deletes a draft package that is not the Season's last one. The API answers 204 No Content.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param planKey the package (Plan) key
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ */
+ public void deleteSeasonPlan(String seasonKey, String planKey, String idempotencyKey) {
+ http.mutationWithHeaderReplay(
+ "DELETE", path(seasonKey, "/plans/" + encode(planKey)), null, idempotencyKey);
+ }
+
+ /**
+ * Activates the Season structure and publishes every draft package in one retryable call.
+ *
+ *
Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map publishSeason(String seasonKey, String idempotencyKey) {
+ return http.postWithHeaderReplay(path(seasonKey, "/publish"), null, idempotencyKey);
+ }
+
+ /**
+ * Runs a server-side hold and release that proves the Season buyer path, with default options.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map createSeasonCheckoutTest(String seasonKey, String idempotencyKey) {
+ return createSeasonCheckoutTest(seasonKey, null, idempotencyKey);
+ }
+
+ /**
+ * Runs a server-side hold and release that proves the Season buyer path.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param params the optional request body ({@code planKey}, {@code quantity}), or {@code null}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map createSeasonCheckoutTest(
+ String seasonKey, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(path(seasonKey, "/checkout-tests"), params, idempotencyKey);
+ }
+
+ /**
+ * Lists recent Season checkout tests, newest first.
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response
+ */
+ public Map listSeasonCheckoutTests(String seasonKey) {
+ return http.get(path(seasonKey, "/checkout-tests"));
+ }
+
+ /**
+ * Replaces a package's price table, per chart category, in minor units.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param planKey the package (Plan) key
+ * @param params the request body: {@code prices}, and optionally {@code currency}; each price
+ * takes {@code categoryKey}, {@code unitPrice} and an optional {@code priceTypeKey}
+ * ({@code adult}, the default, {@code child}, {@code concession}, {@code senior} or
+ * {@code student})
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map replaceSeasonPackagePrices(
+ String seasonKey, String planKey, Map params, String idempotencyKey) {
+ return http.mutationWithHeaderReplay(
+ "PUT", path(seasonKey, "/plans/" + encode(planKey) + "/prices"), params, idempotencyKey);
+ }
+
+ /**
+ * Lists every package price table for the Season. Each price carries its
+ * {@code priceTypeKey} and {@code priceTypeLabel}.
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response
+ */
+ public Map listSeasonPrices(String seasonKey) {
+ return http.get(path(seasonKey, "/prices"));
+ }
+
+ /**
+ * Adds a performance to a published package and extends its allocations.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param planKey the package (Plan) key
+ * @param params the request body: {@code eventKey}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map attachSeasonPlanPerformance(
+ String seasonKey, String planKey, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ path(seasonKey, "/plans/" + encode(planKey) + "/performances"), params, idempotencyKey);
+ }
+
+ /**
+ * Removes a performance from a published package and releases its allocations.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param planKey the package (Plan) key
+ * @param eventKey the performance's Event key
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map deleteSeasonPlanPerformance(
+ String seasonKey, String planKey, String eventKey, String idempotencyKey) {
+ return http.mutationWithHeaderReplay(
+ "DELETE",
+ path(seasonKey, "/plans/" + encode(planKey) + "/performances/" + encode(eventKey)),
+ null,
+ idempotencyKey);
+ }
+
+ /**
+ * Marks a performance past so it stops blocking new Season sales. A cancelled date answers
+ * {@code 409 performance_cancelled}. On a season-seats season the date first leaves every
+ * season seat: while that finishes the answer is a {@code 202} (check with
+ * {@link #isDateLeavePending}).
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param eventKey the performance's Event key
+ * @param params the request body, which may be empty or carry {@code force}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map markSeasonPerformancePast(
+ String seasonKey, String eventKey, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ path(seasonKey, "/performances/" + encode(eventKey) + "/past"), params, idempotencyKey);
+ }
+
+ /**
+ * Returns one Season occurrence allocation to ordinary Event inventory.
+ *
+ * Single attempt: the server makes a repeat with the same {@code actionId} exact, so
+ * reconcile an unknown outcome by sending the same body again yourself.
+ *
+ * @param seasonKey the Season key
+ * @param eventKey the occurrence's Event key
+ * @param params the request body: {@code actionId}, {@code bookingRef},
+ * {@code planActivationId}, {@code labels} and {@code source}
+ * @return the decoded response
+ */
+ public Map returnSeasonOccurrenceInventory(
+ String seasonKey, String eventKey, Map params) {
+ return http.post(path(seasonKey, "/occurrences/" + encode(eventKey) + "/returns"), params);
+ }
+
+ /**
+ * Reclaims returned occurrence inventory while it is still free.
+ *
+ * Single attempt: the server makes a repeat with the same {@code actionId} exact.
+ *
+ * @param seasonKey the Season key
+ * @param eventKey the occurrence's Event key
+ * @param params the request body: {@code actionId}, {@code returnActionId},
+ * {@code bookingRef}, {@code planActivationId}, {@code labels} and {@code source}
+ * @return the decoded response
+ */
+ public Map reclaimSeasonOccurrenceInventory(
+ String seasonKey, String eventKey, Map params) {
+ return http.post(path(seasonKey, "/occurrences/" + encode(eventKey) + "/reclaims"), params);
+ }
+
+ /**
+ * Lists the first page of Season ticket holders.
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response
+ */
+ public Map listSeasonHolders(String seasonKey) {
+ return listSeasonHolders(seasonKey, null, null, null, null);
+ }
+
+ /**
+ * Lists Season ticket holders, one page at a time. Null filters are not sent.
+ *
+ * @param seasonKey the Season key
+ * @param q search by holder name, email, reference, order number or seat, or {@code null}
+ * @param status only holders in this state, or {@code null}
+ * @param cursor the cursor from the previous page, or {@code null}
+ * @param limit the page size, or {@code null} for the server default
+ * @return the decoded response
+ */
+ public Map listSeasonHolders(
+ String seasonKey, String q, String status, String cursor, Integer limit) {
+ return http.get(
+ path(seasonKey, "/holders"),
+ body("q", q, "status", status, "cursor", cursor, "limit", limit));
+ }
+
+ /**
+ * Refunds a Season order in full through its payment provider.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param orderId the order id
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map refundSeasonOrder(
+ String seasonKey, String orderId, String idempotencyKey) {
+ return refundSeasonOrder(seasonKey, orderId, null, idempotencyKey);
+ }
+
+ /**
+ * Refunds a Season order in full or in part through its payment provider.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param orderId the order id
+ * @param params the optional request body ({@code amountMinor}), or {@code null} for a full refund
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map refundSeasonOrder(
+ String seasonKey, String orderId, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ path(seasonKey, "/orders/" + encode(orderId) + "/refund"), params, idempotencyKey);
+ }
+
+ /**
+ * Cancels a Season order without moving money and releases every date.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param orderId the order id
+ * @param params the request body: {@code reason}, plus any optional fields
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map cancelSeasonOrder(
+ String seasonKey, String orderId, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ path(seasonKey, "/orders/" + encode(orderId) + "/cancel"), params, idempotencyKey);
+ }
+
+ /**
+ * Takes back one date of a Season order and puts its seats back on sale.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param orderId the order id
+ * @param eventKey the date's Event key
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map cancelSeasonOrderDate(
+ String seasonKey, String orderId, String eventKey, String idempotencyKey) {
+ return cancelSeasonOrderDate(seasonKey, orderId, eventKey, null, idempotencyKey);
+ }
+
+ /**
+ * Takes back one date of a Season order and puts its seats back on sale.
+ *
+ * Header replay: the same idempotency key is reused on every retry.
+ *
+ * @param seasonKey the Season key
+ * @param orderId the order id
+ * @param eventKey the date's Event key
+ * @param params the optional request body ({@code actionId}), or {@code null}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map cancelSeasonOrderDate(
+ String seasonKey,
+ String orderId,
+ String eventKey,
+ Map params,
+ String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ path(seasonKey, "/orders/" + encode(orderId) + "/dates/" + encode(eventKey) + "/cancel"),
+ params,
+ idempotencyKey);
+ }
+
+ /**
+ * Emails a Season order's tickets again, to the address on the order.
+ *
+ * Single attempt, never retried automatically.
+ *
+ * @param seasonKey the Season key
+ * @param orderId the order id
+ * @return the decoded response
+ */
+ public Map resendSeasonOrderTickets(String seasonKey, String orderId) {
+ return resendSeasonOrderTickets(seasonKey, orderId, null);
+ }
+
+ /**
+ * Emails a Season order's tickets again.
+ *
+ * Single attempt, never retried automatically.
+ *
+ * @param seasonKey the Season key
+ * @param orderId the order id
+ * @param params the optional request body ({@code email}), or {@code null}
+ * @return the decoded response
+ */
+ public Map resendSeasonOrderTickets(
+ String seasonKey, String orderId, Map params) {
+ return http.post(path(seasonKey, "/orders/" + encode(orderId) + "/resend"), params);
+ }
+
+ /**
+ * Retrieves hosted renewal links, payments and emails for the first page of offers.
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response, with the {@code offers} and {@code nextCursor}
+ */
+ public Map retrieveSeasonHostedRenewals(String seasonKey) {
+ return retrieveSeasonHostedRenewals(seasonKey, null, null);
+ }
+
+ /**
+ * Retrieves hosted renewal links, payments and emails per offer, one page at a time, newest
+ * first. Null arguments are not sent.
+ *
+ * @param seasonKey the Season key
+ * @param cursor the {@code nextCursor} from the previous page, or {@code null}
+ * @param limit offers a page, 1-500, or {@code null} for 500
+ * @return the decoded response, with the {@code offers} and {@code nextCursor} (null on the
+ * last page)
+ */
+ public Map retrieveSeasonHostedRenewals(String seasonKey, String cursor, Integer limit) {
+ return http.get(path(seasonKey, "/renewal-hosted"), body("cursor", cursor, "limit", limit));
+ }
+
+ /**
+ * Makes a new renewal link for one holder; the old link stops working.
+ *
+ * Single attempt, never retried automatically: the new link is shown once.
+ *
+ * @param seasonKey the Season key
+ * @param offerId the renewal offer id
+ * @return the decoded response
+ */
+ public Map rotateSeasonRenewalOfferLink(String seasonKey, String offerId) {
+ return http.post(path(seasonKey, "/renewal-offers/" + encode(offerId) + "/link"));
+ }
+
+ /**
+ * Sets the name and email a renewal offer is sent to.
+ *
+ * Single attempt; the server applies a repeat of the same contact exactly once.
+ *
+ * @param seasonKey the Season key
+ * @param offerId the renewal offer id
+ * @param params the request body: {@code email} and/or {@code name}
+ * @return the decoded response
+ */
+ public Map updateSeasonRenewalOfferContact(
+ String seasonKey, String offerId, Map params) {
+ return http.post(
+ path(seasonKey, "/renewal-offers/" + encode(offerId) + "/contact"), params);
+ }
+
+ /**
+ * Emails renewal invitations now, and reminders before the deadline, for every offer.
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response
+ */
+ public Map createSeasonRenewalNotices(String seasonKey) {
+ return createSeasonRenewalNotices(seasonKey, null);
+ }
+
+ /**
+ * Emails renewal invitations now, and reminders before the deadline.
+ *
+ * Single attempt; the server does not send the same notice twice.
+ *
+ * @param seasonKey the Season key
+ * @param params the optional request body ({@code offerIds}, at most 20,000; more is refused
+ * with {@code 422 too_many_offer_ids}; or instead {@code batchId}, every open offer one
+ * {@code createSeasonRenewalOffers} batch made), or {@code null} for every open offer
+ * @return the decoded response
+ */
+ public Map createSeasonRenewalNotices(
+ String seasonKey, Map params) {
+ return http.post(path(seasonKey, "/renewal-notices"), params);
+ }
+
+ /**
+ * Sends one holder a new renewal invitation.
+ *
+ * Single attempt, never retried automatically.
+ *
+ * @param seasonKey the Season key
+ * @param offerId the renewal offer id
+ * @return the decoded response
+ */
+ public Map resendSeasonRenewalOffer(String seasonKey, String offerId) {
+ return http.post(path(seasonKey, "/renewal-offers/" + encode(offerId) + "/resend"));
+ }
+
+ /**
+ * Retrieves what renewing an offer costs, priced as the SeatLayer checkout will charge it.
+ *
+ * {@code problem} is null when SeatLayer checkout can take the renewal now; otherwise it
+ * says why not.
+ *
+ * @param seasonKey the Season key
+ * @param offerId the renewal offer id
+ * @return the decoded response
+ */
+ public Map retrieveSeasonRenewalQuote(String seasonKey, String offerId) {
+ return http.get(path(seasonKey, "/renewal-offers/" + encode(offerId) + "/quote"));
+ }
+
+ /**
+ * Records that the holder means to renew, for a renewal taken by phone or at the box office,
+ * so your own checkout can commit the offer.
+ *
+ * Single attempt; a repeat answers the same offer.
+ *
+ * @param seasonKey the Season key
+ * @param offerId the renewal offer id
+ * @return the decoded response
+ */
+ public Map createSeasonRenewalIntent(String seasonKey, String offerId) {
+ return http.post(path(seasonKey, "/renewal-offers/" + encode(offerId) + "/intent"));
+ }
+
+ /**
+ * Starts a SeatLayer checkout that renews an offer, with no hosted page. Send the buyer to
+ * {@code payment.url}; paying renews the offer.
+ *
+ * Header replay: the same idempotency key is reused on every retry and answers the same
+ * order.
+ *
+ * @param seasonKey the Season key
+ * @param offerId the renewal offer id
+ * @param params the request body: {@code returnUrl} (on one of the organization's allowed
+ * domains), plus optional {@code buyerEmail}, {@code buyerName} and {@code provider}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response
+ */
+ public Map createSeasonRenewalCheckout(
+ String seasonKey, String offerId, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ path(seasonKey, "/renewal-offers/" + encode(offerId) + "/checkout"), params, idempotencyKey);
+ }
+
+ /**
+ * Retrieves Season money, seats, holders and renewals as totals.
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response
+ */
+ public Map retrieveSeasonSalesReport(String seasonKey) {
+ return http.get(path(seasonKey, "/reports/sales"));
+ }
+
+ /**
+ * Retrieves the seats still free per package and per date.
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response
+ */
+ public Map retrieveSeasonSeatsReport(String seasonKey) {
+ return http.get(path(seasonKey, "/reports/seats"));
+ }
+
+ /**
+ * Downloads every Season ticket holder as CSV.
+ *
+ * @param seasonKey the Season key
+ * @return the CSV text, exactly as the API sent it
+ */
+ public String exportSeasonHoldersCsv(String seasonKey) {
+ return exportSeasonHoldersCsv(seasonKey, null, null);
+ }
+
+ /**
+ * Downloads the matching Season ticket holders as CSV. Null filters are not sent.
+ *
+ * @param seasonKey the Season key
+ * @param q search by holder name, email, reference, order number or seat, or {@code null}
+ * @param status only holders in this state, or {@code null}
+ * @return the CSV text, exactly as the API sent it
+ */
+ public String exportSeasonHoldersCsv(String seasonKey, String q, String status) {
+ return http.getText(path(seasonKey, "/reports/holders.csv"), body("q", q, "status", status));
+ }
+
+ /**
+ * Downloads every Season order SeatLayer took as CSV.
+ *
+ * @param seasonKey the Season key
+ * @return the CSV text, exactly as the API sent it
+ */
+ public String exportSeasonOrdersCsv(String seasonKey) {
+ return http.getText(path(seasonKey, "/reports/orders.csv"), null);
+ }
+
+ /**
+ * Retrieves Season seats sold per package and per date.
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response
+ */
+ public Map retrieveSeasonSeatCounts(String seasonKey) {
+ return http.get(path(seasonKey, "/seat-counts"));
+ }
+
+ /**
+ * Refunds every SeatLayer order holding a cancelled date, as a job. Follow it with
+ * {@link #retrieveSeasonBulkJob}.
+ *
+ * Header replay: the same idempotency key is reused on every retry and replays the same job.
+ *
+ * @param seasonKey the Season key
+ * @param eventKey the cancelled date's Event key
+ * @param params the request body: {@code amount} ({@code per_date}, the date's share of each
+ * order; {@code full} is refused with {@code 422 date_refund_per_date_only}, so refund a
+ * whole order with the order refund) and optionally {@code reason}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response, with the {@code job}
+ */
+ public Map refundSeasonPerformance(
+ String seasonKey, String eventKey, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ path(seasonKey, "/performances/" + encode(eventKey) + "/refunds"), params, idempotencyKey);
+ }
+
+ /**
+ * Releases the seats of every lapsed renewal offer, as a job. An offer extended before its
+ * turn is skipped and keeps its seat. Follow it with {@link #retrieveSeasonBulkJob}.
+ *
+ * Header replay: the same idempotency key is reused on every retry and replays the same job.
+ *
+ * @param seasonKey the Season key
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response, with the {@code job}
+ */
+ public Map releaseSeasonLapsedOffers(String seasonKey, String idempotencyKey) {
+ return http.postWithHeaderReplay(
+ path(seasonKey, "/renewal-offers/release-lapsed"), null, idempotencyKey);
+ }
+
+ /**
+ * Lists the Season's bulk jobs, newest first (100 at most).
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response, with the {@code jobs}
+ */
+ public Map listSeasonBulkJobs(String seasonKey) {
+ return http.get(path(seasonKey, "/jobs"));
+ }
+
+ /**
+ * Retrieves one bulk job with its counts, its {@code summary} (empty until it completes) and
+ * up to 500 failed items.
+ *
+ * @param seasonKey the Season key
+ * @param jobId the job id
+ * @return the decoded response, with the {@code job}
+ */
+ public Map retrieveSeasonBulkJob(String seasonKey, String jobId) {
+ return http.get(path(seasonKey, "/jobs/" + encode(jobId)));
+ }
+
+ /**
+ * Sets the Season's seats aside on every date: every seat its packages price, minus
+ * {@code keepForSingleTickets}. The answer is {@code 202} with the {@code job} (a
+ * {@code season_block_set_aside} job to follow with {@link #retrieveSeasonBulkJob}) and the
+ * {@code block}. On an active Season block mode turns on by itself once every date has the
+ * seats ({@code season.block.ready}); on a draft, Publish turns it on. Season seats must be on
+ * for the Season ({@code 409 season_block_not_enabled} otherwise).
+ *
+ * Header replay: the same idempotency key is reused on every retry and replays the same
+ * answer.
+ *
+ * @param seasonKey the Season key
+ * @param params the request body: {@code expectedRevision}, and optionally
+ * {@code keepForSingleTickets} ({@code sectionIds}, {@code categoryKeys} or {@code labels})
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response, with the {@code job} and the {@code block}
+ */
+ public Map setAsideSeasonBlock(
+ String seasonKey, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(path(seasonKey, "/block"), params, idempotencyKey);
+ }
+
+ /**
+ * Retrieves the Season's seats set aside on every date: the {@code block} with its
+ * {@code mode} ({@code block} once on, else {@code per_hold}), {@code state}, {@code counts}
+ * and each date's {@code state}.
+ *
+ * @param seasonKey the Season key
+ * @return the decoded response, with the {@code block}
+ */
+ public Map retrieveSeasonBlock(String seasonKey) {
+ return http.get(path(seasonKey, "/block"));
+ }
+
+ /**
+ * Releases season seats to single sale: every unsold seat ({@code scope}
+ * {@code {"all": true}}), or the sections, categories or seats named. The answer is
+ * {@code 202} with the {@code job} (a {@code season_block_release} job to follow with
+ * {@link #retrieveSeasonBulkJob}) and the {@code block}. {@code season.block.released} is sent
+ * once it has run on every date.
+ *
+ * Header replay: the same idempotency key is reused on every retry and replays the same
+ * release.
+ *
+ * @param seasonKey the Season key
+ * @param params the request body: {@code expectedRevision} and {@code scope}, and optionally
+ * {@code eventKeys} (those dates only; left out, every date still to come), {@code at}
+ * (an ISO time to release at; left out, now) and {@code reason}
+ * @param idempotencyKey a stable key, or {@code null} to generate one
+ * @return the decoded response, with the {@code job} and the {@code block}
+ */
+ public Map releaseSeasonBlock(
+ String seasonKey, Map params, String idempotencyKey) {
+ return http.postWithHeaderReplay(path(seasonKey, "/block/release"), params, idempotencyKey);
+ }
}
diff --git a/src/main/java/io/seatlayer/SeatLayer.java b/src/main/java/io/seatlayer/SeatLayer.java
index 7bf063e..a7498d2 100644
--- a/src/main/java/io/seatlayer/SeatLayer.java
+++ b/src/main/java/io/seatlayer/SeatLayer.java
@@ -20,7 +20,10 @@ public final class SeatLayer {
private final Charts charts;
private final Channels channels;
private final Events events;
+ private final EventSeries eventSeries;
+ private final Holders holders;
private final Inventory inventory;
+ private final Orders orders;
private final PerformanceGroups performanceGroups;
private final Seasons seasons;
private final Sessions sessions;
@@ -38,7 +41,10 @@ private SeatLayer(Builder builder) {
this.charts = new Charts(http);
this.channels = new Channels(http);
this.events = new Events(http);
+ this.eventSeries = new EventSeries(http);
+ this.holders = new Holders(http);
this.inventory = new Inventory(http);
+ this.orders = new Orders(http);
this.performanceGroups = new PerformanceGroups(http);
this.seasons = new Seasons(http);
this.sessions = new Sessions(http);
@@ -64,10 +70,37 @@ public Events events() {
return events;
}
+ /**
+ * Event series: dated events planned from one schedule and changed together.
+ *
+ * @return the event series resource
+ */
+ public EventSeries eventSeries() {
+ return eventSeries;
+ }
+
+ /**
+ * Season ticket holders, their tickets and transfers, and the customer list.
+ *
+ * @return the holders resource
+ */
+ public Holders holders() {
+ return holders;
+ }
+
public Inventory inventory() {
return inventory;
}
+ /**
+ * Orders across events and seasons, and one event's orders, refunds and cancellations.
+ *
+ * @return the orders resource
+ */
+ public Orders orders() {
+ return orders;
+ }
+
/** Fixed multi-performance lifecycle and host-side booking coordination. */
public PerformanceGroups performanceGroups() {
return performanceGroups;
diff --git a/src/main/java/io/seatlayer/SeatLayerHttpClient.java b/src/main/java/io/seatlayer/SeatLayerHttpClient.java
index 5eecce1..4a83241 100644
--- a/src/main/java/io/seatlayer/SeatLayerHttpClient.java
+++ b/src/main/java/io/seatlayer/SeatLayerHttpClient.java
@@ -106,6 +106,24 @@ private Map performRequest(
Object body,
boolean headerReplay,
String idempotencyKey) {
+ Response response =
+ exchange(method, path, query, body, headerReplay, idempotencyKey, "application/json");
+ if (response.status() == 204 || response.body() == null || response.body().isBlank()) {
+ return Map.of();
+ }
+ Object decoded = Json.read(response.body());
+ return decoded instanceof Map ? Json.readObject(response.body()) : Map.of("data", decoded);
+ }
+
+ /** Sends with auth, idempotency and retry, and returns the 2xx response undecoded. */
+ private Response exchange(
+ String method,
+ String path,
+ Map query,
+ Object body,
+ boolean headerReplay,
+ String idempotencyKey,
+ String accept) {
StringBuilder url = new StringBuilder(baseUrl).append(path);
if (query != null && !query.isEmpty()) {
@@ -124,7 +142,7 @@ private Map performRequest(
Map headers = new LinkedHashMap<>();
headers.put("Authorization", "Bearer " + secretKey);
- headers.put("Accept", "application/json");
+ headers.put("Accept", accept);
headers.put("User-Agent", "seatlayer-java");
String payload = null;
@@ -159,11 +177,7 @@ private Map performRequest(
}
if (response.status() >= 200 && response.status() < 300) {
- if (response.status() == 204 || response.body() == null || response.body().isBlank()) {
- return Map.of();
- }
- Object decoded = Json.read(response.body());
- return decoded instanceof Map ? Json.readObject(response.body()) : Map.of("data", decoded);
+ return response;
}
Map errorBody;
@@ -197,6 +211,12 @@ Map