Partner event API

Contract: v1. Updated: 18 October 2026.

Your website displays events and lets customers select a ticket type and quantity. SPORTSHUB handles the booking after you open its hosted flow.

Before you start

Contact SPORTSHUB to enable your integration and receive a partner key. Confirm the website origins you will use, such as https://partner.example. Include www separately if your website uses both hostnames. An origin contains the scheme, hostname and port, with no page path or trailing slash.

Use the key supplied for the environment you are calling. It is intended for browser JavaScript and is visible to visitors. It identifies your registered integration.

Send requests

Send both operations to the same URL with POST:

API URL

https://australia-southeast1-socialsportsprod.cloudfunctions.net/globalAppController

Request headers

Content-Type: application/json
X-Sportshub-Partner-Key: <partner-key>

Replace <partner-key> with your supplied key. For browser requests, set credentials: "omit". The browser supplies the Origin header; do not set it yourself. Serve the integration from a registered HTTPS origin. File previews and unregistered hostnames cannot call this production API.

Each request contains endpointType and data. Check the HTTP status before reading the successful response’s data.

Error response

{
  "errorMessage": "Example error message"
}

Invalid request envelopes return HTTP 400. A missing, invalid or disabled key returns HTTP 401; a denied origin returns HTTP 403. Methods other than POST return HTTP 405; browsers may use OPTIONS for preflight.

Key or origin failures may appear as a fetch or CORS error in browser JavaScript. Check your key and registered origin with SPORTSHUB before making further requests.

This reference covers the production API. Contact us to arrange a test environment before testing bookings.

All IDs and event details in the examples below are synthetic.

Response compatibility

Responses may contain additional fields, including within event and ticket objects. Validate the required fields for each operation and the types of fields your integration uses. Ignore unrecognized fields; do not reject a response solely because it contains them. Use the documented fields to build your own display model instead of storing, logging, or forwarding the full response.

If a field has an unrecognized named value, treat that value as unsupported and keep displaying unaffected event details. Do not infer booking availability or payment support from it. Missing required fields or incorrectly typed fields are unexpected responses; follow the operation’s error and retry guidance.

We may add response fields without changing the major contract version. Within a major version, existing documented fields retain their types and meanings. Removing or renaming fields, changing their types or meanings, or adding mandatory requirements requires a new major contract version and migration instructions.

1. Load your public events

Request body

{
  "endpointType": "GET_PARTNER_EVENTS",
  "data": {}
}

Your partner key selects your public event feed.

The feed contains active, public events whose start time is at or after the request time. Events without a start time are omitted. Events that have already started are omitted, even if registration remains open. Future paused, sold-out, and registration-closed events can still appear.

Events are sorted by start time, then event ID. The response includes the full upcoming feed, without pagination. A successful empty result is {"data":{"events":[]}}.

Successful response

{
  "data": {
    "events": [
      {
        "eventId": "example-event",
        "name": "Example sports session",
        "description": "A sports session for this API example.",
        "location": "Example Sports Centre",
        "startDate": "2027-01-10T22:00:00Z",
        "endDate": "2027-01-11T00:00:00Z",
        "registrationDeadline": "2027-01-10T21:00:00Z",
        "image": null,
        "thumbnail": null,
        "eventTags": ["volleyball"],
        "paused": false,
        "paymentsActive": true,
        "waitlistEnabled": true,
        "bookingApprovalEnabled": false,
        "maxTicketsPerTransaction": 4,
        "supportedPaymentProviders": ["STRIPE"],
        "ticketTypes": [
          {
            "id": "example-ticket-type",
            "name": "General Admission",
            "priceCents": 1800,
            "soldOut": false,
            "vacancy": 12
          }
        ]
      }
    ]
  }
}

Event fields

Every listed field is present. Fields marked nullable can contain JSON null.

These flags help your website explain the event. They do not guarantee that a booking will succeed. SPORTSHUB checks the current event and ticket state when the customer books.

Use supportedPaymentProviders for payment labels. Show Stripe only when the list contains STRIPE; ignore unrecognized provider values. The list does not guarantee payment readiness or ticket availability. An empty list does not by itself rule out a free booking or waitlist. The booking operation below uses Stripe and does not accept a payment-provider selection.

Ticket fields

Ticket types are sorted with General Admission first, followed by name and ID.

Some events can return ticketTypes: []. You may display these events, but cannot start a booking through this contract until the organiser configures a ticket type. Do not invent an ID from the event name or price.

A sold-out ticket can lead to a waitlist when waitlistEnabled is true. Keep that option available; SPORTSHUB checks whether the request can proceed.

Feed errors and refresh

Fetch on page load. If you refresh while the page remains visible, we recommend no more than once per minute. Keep only the data needed for the current page; responses use Cache-Control: no-store and must not go into shared HTTP caches. Availability can change between the feed request and checkout.

2. Start a booking

Before enabling bookings on your site, test the handoff with your event and ticket types.

Call INIT_PARTNER_FULFILMENT_SESSION after a customer chooses a ticket type and quantity and presses Book. Send one request at a time. Do not prefetch booking sessions.

Request body

{
  "endpointType": "INIT_PARTNER_FULFILMENT_SESSION",
  "data": {
    "eventId": "example-event",
    "numTickets": 1,
    "eventTicketTypeId": "example-ticket-type"
  }
}

Send exactly these three inputs. Additional inputs are rejected. Use an event and ticket type from your feed; private events and other organisers’ events are unavailable through this operation.

Successful response

{
  "data": {
    "entryUrl": "https://www.sportshub.net.au/fulfilment/example-session/example-step?hideSportshubNavbar=true"
  }
}

A successful response starts a session and returns its booking URL. It does not confirm a booking or payment. SPORTSHUB hosts the remaining forms, checkout, waitlist, approval, and confirmation steps as applicable.

Open the booking URL

Check that entryUrl is a nonempty, absolute URL with origin https://www.sportshub.net.au, a path starting with /fulfilment/, and no username or password. Then open the URL unchanged. Use the approved SPORTSHUB website origin when testing in another environment.

Treat entryUrl as a private guest access credential: anyone with the URL may access that session. Keep it in transient page state and out of analytics, shared caches, error messages and logs.

Retry guidance

Do not retry INIT after a timeout, connection failure, server error (HTTP 5xx), or unreadable or unexpected success response. Do not show a “Try again” button for INIT while its outcome is unknown. It may already have created a session or reserved tickets. Tell the customer that the booking attempt could not be confirmed.

If you received a valid entryUrl but navigation failed, reopen that same URL. Do not start another session to recover from a navigation failure.

Booking errors

Readable JSON errors use errorMessage. Handle every non-success status; do not rely on the message text as a stable error code. A network or CORS failure may have no readable response.