# Third-party member tickets

OCAPI supports the integration of third-party member ticket schemes to enable patrons to redeem tickets from third-party systems using
a card number (referred to as a "ticket redemption card").

Third-party member tickets enable promotional and reward-based ticket configuration and validation to be done outside of Vista's systems during an order flow.

NOTE
A third-party member ticket scheme can also be integrated with Vista Loyalty to enable additional rules to be run to calculate eligibility of the tickets for the member. The tickets linked to these third-party schemes are validated and processed completely within Vista software.

## Identifying available third-party member schemes

The [GetThirdPartyTicketMemberSchemes](/openapi/digital-platform/openapi/third-party-member-schemes/ocapithirdpartymemberschemes_getthirdpartymemberschemesforsite/)
endpoint returns the list of third-party schemes available for a given cinema site.

```json
[
  {
    "id": "string",
    "name": {
      "text": "string",
      "translations": []
    },
    "cardNumberFormat": {
      "partialFormat": null,
      "fullFormat": null,
      "prefixLength": 0
    },
    "redemptionLimitPerShowtime": null
  }
]
```

NOTE
A third-party member scheme may also be configured for [subscription tickets](/digital-platform/orders/standard-orders/subscription-tickets#subscription-tickets).

## Third-party scheme ticket flow

```mermaid
flowchart TB
    A(Add ticket redemption card to order) --> B
    B(Add third-party member tickets to order)
```

## Add ticket redemption card to order

A third-party member card must be added to an in-progress order via the [AddTicketRedemptionCard](/openapi/digital-platform/openapi/ticket-redemption-cards/ocapiorderticketredemptioncards_addticketredemptioncard/) endpoint.

```json
{
  "type": "ThirdPartyMemberCard",
  "credentials": {
    "cardNumber": "string",
    "thirdPartyMemberSchemeId": "string"
  },
  "showtimeId": "string"
}
```

NOTE
A ticket redemption card can be the following types:

- `ThirdPartyMemberCard` - used for third-party member tickets.
- `MemberTicketRedemptionCard` - used for [subscription tickets](/digital-platform/orders/standard-orders/subscription-tickets#add-ticket-redemption-card-to-order).


This endpoint validates the provided card, stores its details against the order, and returns its `id`, `redemptionLimit`, and other details.

```json
{
  "ticketRedemptionCard": {
    "id": "string",
    "type": "ThirdPartyMemberCard",
    "maskedCardNumber": "string",
    "subscriptionId": 0,
    "thirdPartyMemberSchemeId": "string",
    "memberName": {
      "givenName": "string",
      "familyName": "string",
      "middleName": "string"
    }
  },
  "redemptionLimit": {
    "isUnlimited": true,
    "maximum": 0,
    "minimum": 0
  }
}
```

## Add third-party member tickets to order

Third-party member tickets are added to the order via the [SetShowtime](/openapi/digital-platform/openapi/showtimes/ocapiordershowtimes_setshowtime/) endpoint.

```json
{
  "tickets": [
    {
      "id": "string",
      "ticketTypeId": "string",
      "ticketRedemptionCardId": "string"
    }
  ]
}
```

When adding a third-party member ticket, the `ticketRedemptionCardId` is required and must be set to the `id` of the added ticket redemption card.

The request will be declined if the requested number of tickets exceeds the `redemptionLimit` of the ticket redemption card, or if other
validation rules in the third-party system are not met.

## Committing third-party tickets in the third-party system

It is important to note that, unlike voucher tickets or loyalty member reward tickets, third-party member ticket redemptions are committed in the third-party system *as soon as they are added* to the order, not during order completion.

As such, if the order is abandoned, the patron may not be able to re-use their third-party member tickets until the previous order expires or is cancelled
(which will reverse the commit in the third-party system).