Scheduled films

Scheduled films are films that have at least one session scheduled at a physical site. These films are much more likely to be useful than the list of all films which have ever been shown at a cinema, so endpoints have been created specifically for retrieving these films.

Advance bookings

Advance booking rules are considered when retrieving scheduled films. If these rules mean that no tickets are available to be purchased for a film then the film will not be returned unless the "Advertise Open Sessions in Advance" option has been set on the advance booking rule. As loyalty members can be eligible for making advance bookings earlier than other customers, a loyalty member can also be passed in to most endpoints to ensure that movies only available to loyalty members are returned. This can be accomplished with the userSessionId parameter if the member has an active session, or the loyaltyMembershipId parameter if you want to search as a particular loyalty member.

Retrieving all scheduled films

Retrieving all scheduled films can be accomplished with the ScheduledFilms and GetScheduledFilms endpoints. These endpoints serve a similar purpose but GetScheduledFilms has more filtering parameters available, which can be viewed on the API reference page

These endpoints will return all films that:

• Have at least one scheduled session
• Are available to purchase or have an advance booking rule with "Advertise Open Sessions in Advance" set
• Match any passed in filtering parameters

Retrieving scheduled films for batch clients

If using Connect in a Batch Client manner (as specified in the Reference Data Overview) the GetBatchDataForCinema endpoint can return all Scheduled Films for the passed in cinema, equivalent to calling the GetScheduledFilms endpoint with a cinemaId.

Now showing scheduled films

The GetNowShowingScheduledFilms endpoint returns all scheduled films (films returned by the GetScheduledFilms endpoint) that within the Now Showing window.

This endpoints will return all films that:

• Have at least one scheduled session
• Are available to purchase or have an advance booking rule with "Advertise Open Sessions in Advance" set
• Have a session within the Now Showing window
• Match any passed in filtering parameters

Now showing window

The Now Showing window is a date range starting on the current date and extending a number of days defined by the DaysAheadToFlagSessionsAsNowShowing Connect system setting. Films with sessions within this window are considered "Now Showing" and films with sessions exclusively beyond this window are considered "Coming Soon".

Coming soon scheduled films

The GetComingSoonScheduledFilms endpoint can return films that may not have scheduled sessions but you do want to advertise to customers. This endpoint will return films that are marked as Coming Soon or that only have sessions beyond the Now Showing window.

Unlike the other Scheduled Films endpoints, GetComingSoonScheduledFilms will return one entry for each film, rather than one entry for each film at each cinema. As such, it will return less cinema specific information than the other endpoints.

This endpoint will return all films that:

• Have no sessions, are marked as coming soon, and have an opening date in the future
• Are available to purchase (or would be if they had any sessions) or have an advance booking rule with "Advertise Open Sessions in Advance" set
• Have sessions exclusively beyond the Now Showing window
• Match any passed in filtering parameters

This endpoint is optimized for returning film data, and only returns session-related information if the includeSessions parameter is set to true.

Coming soon films

If a film is marked with the "Include in Coming Soon Films when there are no sessions (unless opening date has passed)" flag and has no scheduled sessions then it will be considered Coming Soon if it has an Opening Date on a day after the current day.

Sales channel filtering

Scheduled Films are filtered based on the sales channels defined for each session. When making API calls it is important to understand what sales channel is being used to filter:

• If the endpoint allows a salesChannel parameter then this will be used to filter the sessions
• If no custom filter is provided the sales channel of the client represented by the connectApiToken header will be used
• If no connectApiToken is provided then the default sales channel configured in Connect will be used