Memberships

Exposes Ventrata membership capabilities to OCTO.

Allow member benefits to be redeemed when making new bookings.

To use this capability add octo/memberships to your Octo-Capabilities header.

Member Login

The first step is to provide some interface for a member login, provide a button on your interface called "Member Login" which when clicked you provide a login form for the member, with 3 possible ways:

• Email We'll then send a verification code to the customer's email which you'll need to repeat in the request to verify the guest's identity.

• Mobile We'll then send a verification code to the customer's email which you'll need to repeat in the request to verify the guest's identity.

• Reference If the booking exists we will then ask for a last name to verify the the guest's identity

Once you've picked an authentication method and collected the info, you make a request:

POST https://api.ventrata.com/octo/memberships/lookup

Request Body

Name	Type	Description
email	string	The customer's email
mobile	string	The customer's mobile
reference	string	Any reference of the booking
verification	string	A verification code

You should send either email, mobile or reference.

Some example request/responses for each method are shown below:

Email

POST /memberships/lookup HTTP/1.1
Content-Type: application/json
Host: api.ventrata.com/octo

{
  "email": "[e-mail]"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "A verification email has been sent to [e-mail]",
  "verified": false,
  "bookings": []
}

Mobile

POST /memberships/lookup HTTP/1.1
Content-Type: application/json
Host: api.ventrata.com/octo

{
  "mobile": "[phone]"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "A verification SMS has been sent to [phone]",
  "verified": false,
  "bookings": []
}

Reference

POST /memberships/lookup HTTP/1.1
Content-Type: application/json
Host: api.ventrata.com/octo

{
  "reference": "X1P2FY"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "Customer last name required for verification",
  "verified": false,
  "bookings": []
}

No Memberships Found

{
  "error": "No membership found with those details"
}

The response will return 400 Bad Request if no memberships were found, otherwise we'll return a message with "verified": false you should then prompt for the verification code and repeat the request with this value.

Verification code for reference will be the last name of the guest. For email and mobile the verification value will be a 6 digit code sent to their email/mobile - whichever was provided.

Once you repeat the request, including the verification field with the verification code, it will verify the member and return a list of memberships that they have.

{
  "message": null,
  "verified": true,
  "memberships": [
    {
      "id": "8d0e6f7a-f720-49c2-989f-72c98ba5d550",
      "title": "Adult Gold Membership",
      "reference": "X1P2FY",
      "contact": {
        "fullName": "Oliver Morgan",
        "emailAddress": "[e-mail]",
        "phoneNumber": "[phone]",
        "locales": ["en"],
        "country": "GB"
      }
    }
  ]
}

If multiple memberships were returned you should provide an interface to pick one, using title and/or contact to differentiate between them.

Product Benefits

Memberships can have multiple benefits, once you have logged in and selected a membership it's important you include a membership object to each request.

GET https://api.ventrata.com/octo/products/{id}

For example to the get product endpoint including the membership object as query parameters:

?membership[reference]=X1P2FY
&membership[verification]=MORGAN
&membership[id]=8d0e6f7a-f720-49c2-989f-72c98ba5d550

You should repeat the reference and verification you provided in the login step, and just add id to specify the membership you want to apply.

Memberships with product benefits will add additional units to the list, you can tell which units belong to the membership benefit by an additional membershipBenefitobject which is otherwise null. For example:

{
  //..rest of the product object
  "options": [
    {
      //..rest of the option object
      "units": [
        {
          //..rest of the unit object
          "membershipBenefit": {
            "id": "ac4e27ea-946a-432b-a4ad-366482aada6b",
            "title": "Membership Admission",
            "description": "Get a free admission and up to 3 companion tickets with your membership."
          }
        }
      ]
    }
  ]
}

If you're rendering this on a page showing the available units to choose from, we recommend you grouping units by membershipBenefit.id and display the units in a highlighted box, for example:

+---------------------------------------------+
| Membership Admission                        |
| Get a free admission and up to 3 companion  |
| tickets with your membership.               |
|                                             |
| Member            $0            (+) 0 (-)   |
| Member Companion  $5            (+) 0 (-)   |
+---------------------------------------------+

  Adult             $10           (+) 0 (-)

Units with "membershipBenefit": null should go at the end as they are now, these are the regular units that weren't made available with the membership.

You would include these units within the unitItems array as you do normally, making sure you are including the membershipobject in the booking request as you do normally.

Offers Benefits

Memberships also provide discounts on availability when using the octo/offerscapability.

When you call POST /availability and POST /availability/calendar you should also send the membership object like so:

POST /availability HTTP/1.1
Content-Type: application/json
Octo-Capabilities: octo/memberships, octo/offers

{
  "productId": "30cc0268-b1db-4baf-8597-c0872fcd3fd3",
  "optionId": "DEFAULT",
  "localDateStart": "YYYY-MM-DD",
  "localDateEnd": "YYYY-MM-DD",
  "units": [
    { "id": "67681a23-c0a4-4deb-a774-e03385ce0890", "quantity": 1 }
  ],
  "membership": {
    "reference": "X1P2FY",
    "verification": "MORGAN",
    "id": "8d0e6f7a-f720-49c2-989f-72c98ba5d550"
  }
}

When using this alongside the octo/offers capability we'll add a membershipBenefit field to the offer object, like so:

{
  //..rest of the availability object
  "offer": {
    //..rest of the offer object
    "membershipBenefit": {
      "id": "FFF",
      "title": "10% Members-only Discount",
      "description": "As a gold member you receive an exclusive 10% discount."
    }
  }
}

Nothing needs to be done to select this offer, it's automatically applied as if you had entered an offerCode or are using a public promotion. The only thing to consider is if offer.membershipBenefit is set, you should display membershipBenefit.title/description in place of offer.title/description if you are displaying that at anywhere.

Booking / Order

Finally when it comes to creating the booking or order (if you're using the octo/cart capability) simply include the membership object as you have been doing in the steps above.

This will associate the booking to the membership and automatically apply any benefits available. For example:

Booking

POST /bookings HTTP/1.1
Content-Type: application/json
Octo-Capabilities: octo/memberships, octo/offers

{
  "productId": "30cc0268-b1db-4baf-8597-c0872fcd3fd3",
  "optionId": "DEFAULT",
  "availabilityId": "f79ea8b7-74bf-436d-a847-2eb820686f25",
  "unitItems": [
    { "unitId": "67681a23-c0a4-4deb-a774-e03385ce0890" }
  ],
  "membership": {
    "reference": "X1P2FY",
    "verification": "MORGAN",
    "id": "8d0e6f7a-f720-49c2-989f-72c98ba5d550"
  }
}

Order

POST /orders HTTP/1.1
Content-Type: application/json
Octo-Capabilities: octo/memberships, octo/offers

{
  "membership": {
    "reference": "X1P2FY",
    "verification": "MORGAN",
    "id": "8d0e6f7a-f720-49c2-989f-72c98ba5d550"
  }
}

We'll then include the membershipand membershipBenefit on the order/booking object so it's clear to see what has been applied.