Session extension to indicate membership inclusive classes

[markthomasUprise]

Which organisation(s) are proposing this issue?

• UpriseVSI - Mark Thomas
• LeisureCentre.com web booking journey for classes activities & membership

Usecase

To enable membership options to be offered inline booking journey.

Please describe why your use case is not covered by the existing specification

Classes are not returned with a flag indicating which Memberships offer the class inclusive of the membership. Details of these Membership offers should be available elsewhere in the API.

What are you proposing should be changed in the specification?

• Extension of GET '/Sessions'
• Extend Offer to include optional Memberships
• For each Membership list MembershipType

Example

"offer": [
    {
        "name": "Non-member price",
        "price": 4.5,
        "priceCurrency": "GBP"
    },
    {
        "name": "Member price",
        "price": 4.5,
        "priceCurrency": "GBP",
        "eligibleCustomerType": "http://openactive.io/ns#Member",
        "Membership": [
            {
                "MembershipTypeId": 0,
                ...
                "MembershipTypeId": n
            }
        ],
    },
    {
        "name": "Member price",
        "price": 3.5,
        "priceCurrency": "GBP",
        "eligibleCustomerType": "http://openactive.io/ns#Member",
        "Membership": [
            {
                "MembershipTypeId": 0,
                ...
                "MembershipTypeId": n
            }
        ],
    }
],

References

MemberShipFlow.pdf

[nickevansuk]

Really great idea! Potentially we could use membership type IDs as references here, so something like the below? This way a membership such as https://api.example.com/memberships/1 could have an offer, which could be purchased, providing an easy route to "upsell" memberships to users looking at Pay as You Go.

So within GET /sessions:

"offers": [
    {
        "name": "Non-member price",
        "price": 4.5,
        "priceCurrency": "GBP"
    },
    {
        "name": "Member price",
        "price": 4.5,
        "priceCurrency": "GBP",
        "eligibleCustomerType": "http://openactive.io/ns#Member",
        "eligibleMembership": [
           "https://api.example.com/memberships/1",
           "https://api.example.com/memberships/2"
        ],
    },
    {
        "name": "Member price",
        "price": 3.5,
        "priceCurrency": "GBP",
        "eligibleCustomerType": "http://openactive.io/ns#Member",
        "eligibleMembership": [
           "https://api.example.com/memberships/3",
           "https://api.example.com/memberships/4"
        ],
    }
],

And as a response to GET /memberships/1 (taking inspiration from this proposal):

  {
    "type": "Membership",
    "id": "https://api.example.com/memberships/1",
    "name": "Off-Peak Fitness",
    "description": "Unlimited access to the gym, fitness classes, swimming pool and select facilities at off-peak times",
    "offers": [
        {
            "price": 45,
            "priceCurrency": "GBP",
            "paymentFrequency": "http://openactive.io/ns#Monthly",
            "url": "https://bookingsystem.example.com/membership/purchase/deep/link/4"
        }
    ]
  }

(N.B. we probably need a whole new proposal for memberships, which includes potentialActions to allow them to be bookable natively. We also need to think about how they can be exposed as open data so they can be referenced from the main session feed.)

[nickevansuk]

One route might be to embed memberships in the feed itself as part of the event:

"offers": [
    {
        "name": "Non-member price",
        "price": 4.5,
        "priceCurrency": "GBP"
    },
    {
        "name": "Member price",
        "price": 4.5,
        "priceCurrency": "GBP",
        "eligibleCustomerType": "http://openactive.io/ns#Member",
        "eligibleMembership": [
           "https://api.example.com/memberships/1",
           "https://api.example.com/memberships/2"
        ],
    },
    {
        "name": "Member price",
        "price": 3.5,
        "priceCurrency": "GBP",
        "eligibleCustomerType": "http://openactive.io/ns#Member",
        "eligibleMembership": [
           "https://api.example.com/memberships/3",
           "https://api.example.com/memberships/4"
        ],
    }
],
"memberships": [
  {
    "type": "Membership",
    "id": "https://api.example.com/memberships/1",
    "name": "Off-Peak Fitness",
    "description": "Unlimited access to the gym, fitness classes, swimming pool and select facilities at off-peak times",
    "offers": [
        {
            "price": 45,
            "priceCurrency": "GBP",
            "paymentFrequency": "http://openactive.io/ns#Monthly",
            "url": "https://bookingsystem.example.com/membership/purchase/deep/link/4"
        }
    ]
  }
]

[peter-dolkens]

Spec will also need to cover those venues who do not wish to make their member rates public.

Some venues will not be happy revealing grandfathered, exclusive, etc rates. In those cases, I think we can just leave "price" off the entry, as such:

"offers": [
    {
        "name": "Non-member price",
        "price": 4.5,
        "priceCurrency": "GBP"
    },
    {
        "name": "Member price",
        "price": 4.5,
        "priceCurrency": "GBP",
        "eligibleCustomerType": "http://openactive.io/ns#Member",
        "eligibleMembership": [
           "https://api.example.com/memberships/1",
           "https://api.example.com/memberships/2"
        ],
    },
    {
        "name": "Private Member price",
        "eligibleCustomerType": "http://openactive.io/ns#Member",
        "eligibleMembership": [
           "https://api.example.com/memberships/3",
           "https://api.example.com/memberships/4"
        ],
    }
],
"memberships": [
  {
    "type": "Membership",
    "id": "https://api.example.com/memberships/1",
    "name": "Off-Peak Fitness",
    "description": "Unlimited access to the gym, fitness classes, swimming pool and select facilities at off-peak times",
    "offers": [
        {
            "price": 45,
            "priceCurrency": "GBP",
            "paymentFrequency": "http://openactive.io/ns#Monthly",
            "url": "https://bookingsystem.example.com/membership/purchase/deep/link/4"
        }
    ]
  }
]

[ldodds]

As a general point of process, I think there's actually two aspects to this proposal:

1. how do we describe member pricing and membership options within Offers. This is an extension/refinement to the modelling opportunity data specification.

2. how do we support bookings by members / existing account holders within the booking specification? This would include ensuring that clients consistently apply rules to recommend prices and potentially checking membership/account holder status of a user.

I want to flag that the second aspect is currently out of scope for v1.0 of the booking API. This is based on the requirements and use cases we have agreed with the community.

Suggest we continue to discuss the changes to the data model here, but noting that the initial changes may be to make this information available as open data before its supported in booking.

[nickevansuk]

Noting here some overlap with #60, where memberships might be better sat inside organizer

Also noting that schema.org's ProgramMembership could be used or subclassed for this purpose.

[nickevansuk]

Also note an exact mapping between the memberships and eligibleMembership approach above and Google Reserve's PaymentOption:

• Google Reserve Merchant ~= OpenActive Event.organizer + OpenActive Event.location

• Google Reserve Service ~= OpenActive Event

• Google Reserve Merchant.PaymentOption ~= OpenActive Event.organizer.membership (this proposal)

• Google Reserve Service.payment_option_id ~= OpenActive Event.offers.eligibleMembership (this proposal)

[nickevansuk]

Further notes on this considering properties that should be included in a membership; we should consider including:

• availabilityStarts "The end of the availability of the product or service included in the offer." and availabilityEnds
• validFrom "The date when the item becomes valid." and validThrough
• eligibleDuration "The duration for which the given offer is valid."
• eligibleQuantity "The interval and unit of measurement of ordering quantities for which the offer or price specification is valid. This allows e.g. specifying that a certain freight charge is valid only for a certain quantity."

availabilityStarts and validFrom

See #59

eligibleDuration

From the [GoodRelations definition of eligibleDuration] (http://www.heppnetz.de/ontologies/goodrelations/v1.html#eligibleDuration):

The minimal and maximal duration for which the given gr:Offering or gr:License is valid. This is mostly used for offers regarding accommodation, the rental of objects, or software licenses. The duration is specified by attaching an instance of gr:QuantitativeValue. The lower and upper boundaries are specified using the properties gr:hasMinValue and gr:hasMaxValue to that instance. If they are the same, use the gr:hasValue property. The unit of measurement is specified using the property gr:hasUnitOfMeasurement with a string holding a UN/CEFACT code suitable for durations, e.g. MON (months), DAY (days), HUR (hours), or MIN (minutes).

So this can represent Google Reserve valid_duration_sec: "Duration of the payment option validity (e.g. 30 day membership).".

Note that eligibleDuration should be restricted to QuantitativeValue with a value and unitCode, rather than allowing a range. So only represent 30 day membership, as a 30-60 day membership is not a usecase we're aware of and will likely cause confusion. The unitCode should be restricted to only temporal codes (e.g. MON (months), DAY (days)). We should also consider allowing for Duration to be used instead of QuantitativeValue as a value eligibleDuration to be consistent with durations elsewhere.

eligibleQuantity

This can represent Google Reserve session_count: "How many sessions this payment option can be used for. Valid only for multi-session / packs, where the value should be > 1."

Makesweat already has notion of passes (see openactive/implementation-tracker#86) but is not marking them up specifically.

Note that eligibleQuantity should be restricted to QuantitativeValue with a value and unitCode, rather than allowing a range. So only represent 10 session pass, as a 10-20 session pass is not a usecase we're aware of and will likely cause confusion. The unitCode should be restricted to only the string C62 i.e. unit (as explained here), to indicate number of sessions included in the pass.

[nickevansuk]

Also perhaps Membership should be named more generically to include "10 session pass" as well as just "monthly membership". So perhaps "AccessPass"?

[nickevansuk]

It would also be useful to investigate PaymentOptionType, ActivationType and UserPurchaseRestriction from Google Reserve to see if we can add an equivalence here, while looking at broader use cases for these too.

[nickevansuk]

Another question is whether eligibleMembership should be able to be specified at Event/FacilityUse level as well as just Offer level (as an event might be eligible in its entirety regardless of which offer is selected). Google Reserve allows this.

Similar requirement to offerTemplate in #60

[nickevansuk]

To add further thoughts to this, the types of membership options seem to break out into two main categories:

• Subscriptions - monthly subscription providing access to a site/sites or set of activities (e.g "Gym and Swim membership", "Off-peak membership")
• Passes - one-off purchase that provides access to a sites/sites or activity/activities for a set a duration or number of visits/sessions (e.g. "1 day pass", "5 class pass", "1 month off-peak pass").

Also it's become apparent that although some publishers want to specify membership options in detail, and provide the option to purchase these, other publishers might want to simply specify a "membership required" flag for an Event or Offer with a link to where to find out more information.

Some properties that might be interesting to think about (see UserPaymentOption of Google Reserve):

• Validity startTime and endTime: Allowed pass will be valid (usable) between startTime and endTime. Attempts to use a user payment option to make a booking outside of this interval will fail. E.g. "Off peak pass"
• Single-use / Multi-use / Unlimited-use: "5 class pass" vs "5 day pass"
• remainingUses: The limit of uses of a pass, e.g. "5 class pass" (could re-use remainingUses?)
• maximumUses: The remaining uses of a pass e.g. "5 class pass, 3 uses remaining" (could re-use maximumUses?)