Subscriptions

Subscriptions allow customers to receive a benefit (such as cheaper or unlimited tickets) in exchange for a fee.

Subscriptions can be one-off or recurring.

Subscription payments

Subscription payments must use the Vista Web Payment Module. Recurring subscriptions must use embedded payments, one-off subscriptions can use embedded or redirect payments.

Subscription call flows

The call flows for subscriptions will vary from client to client, based on the order they want customers to take actions in. Most call flows will contain the following, however:

Sign in or create a Loyalty member

Create a loyalty member

(GET) /ocapi/v1/loyalty/master-data/member-management //TODO: subject to change

Gets the data available to use when updating a Loyalty member's personal details. For example, a list of genres members can select as their preferred genres.

This call may not be required if customers only need to enter limited details to become a member. For example, an email and password.

(POST) /ocapi/v1/members

Creates a new Loyalty member.

(PUT) /ocapi/v1/members/current/photo

Sets the member photo for a loyalty member.

Authenticate a loyalty member

(POST) /ocapi/v1/members/authentication-cookie

Creates a cookie-based authentication session. Recommend for web based clients, as it allows Connect and the Loyalty member's browser to handle the majority of the logic involved in maintaining the authentication session.

(POST) /ocapi/v1/members/authentication-token

Authenticates a member and returns an authentication token. This method is appropriate for clients that don't run on a web browser, or that require granular control of members' authentication.

Get the currently signed in Loyalty member

(GET) /ocapi/v1/members/current

Gets the currently authenticated Loyalty Member.

Get a list of available subscription billing options

(GET) /ocapi/v1/subscription-billing-options

Gets the list of billing options for subscriptions so they can be displayed to the user.

Set the member's primary card

A primary card is required for recurring subscriptions. When members purchase a recurring subscription, the card they use to pay for the subscription will become their primary card automatically. If payment is being taken at a later date, they'll need to select a primary card manually.

See the reference data for Members Payment Cards for the full range of calls available for member cards.

Get the member's payment cards

(GET) /ocapi/v1/members/current/payment-cards

Gets the payment cards for the currently authenticated member.

Add a payment card to the member

(POST) /ocapi/v1/members/current/payment-cards/embedded

Loads and initiates the creation of a member payment card using an embedded UI.

Set the member's primary card

(PUT) /ocapi/v1/members/current/payment-cards/primary

Sets the primary card for the member. The primary card is used to pay for recurring subscriptions whenever payment is due.

Update a member's subscription

Select a one-off subscription or a member's first subscription

The same set is called to sign a member up to a subscription for the first time (regardless of the subscription type) or to purchase a one-off subscription.

(POST) /ocapi/v1/orders/subscription

Creates a subscription order. Requires a currently authenticated member.

(PUT) /ocapi/v1/orders/{orderid}/subscription

Specifies the subscription to be purchased.

Change to a recurring subscription

The same endpoint is used to change from a one-off subscription to a recurring subscription, or from a recurring subscription to a different recurring subscription.

A subscription's CanPurchaseFutureSubscriptionAt must be reached before a member's next subscription can be changed to a recurring subscription.

Requires a primary card to be set for the member. Payment isn't taken immediately. It's taken whenever payment is due for the member's next subscription.

(POST) /ocapi/v1/members/current/subscriptions/next-recurring

Updates the member's next subscription to a recurring subscription. The member doesn't need to be on a recurring subscription currently.

Cancel a recurring subscription

(DELTE) /ocapi/v1/members/current/subscriptions/current

Cancels the member's current subscription. The member's  isCancellationAllowed value determines if their current subscription can be cancelled.

Confirm or update the member's details

(GET) /ocapi/v1/loyalty/master-data/member-management //TODO: subject to change

(GET) /ocapi/v1/members/current

(PUT) /ocapi/v1/members/current/personal-details 

Updates the details of the currently authenticated Loyalty member.

Take payment

(GET) /ocapi/v1/gift-shop/web-payment-methods

Gets the list of available payment methods. Recurring subscriptions must use embedded payments, one-off subscriptions can use embedded or redirect payments.

(POST) /ocapi/v1/orders/{id}/payments/embedded

Creates an embedded payment.

(GET) /ocapi/v1/orders/{id}/payments/embedded/current

Returns the embedded payment's status. Can be used to poll for payment completion. On success, Connect will create an order completion, which the client will need to confirm.

(GET) /ocapi/v1/orders/{id}/completion

Returns an order completion's status. Can be used to poll for order completion.

Refresh the member's details

(GET) /ocapi/v1/members/current