Specifying minimum and maximum tickets

Actionable error messages indicating minimum and maximum number of tickets required in a purchase can be provided to the user through the implementation of ticket constraints. If a user tries to place an order where a line-item violates one of these constraints, an error message will be displayed to the user so the user can adjust their order accordingly.

When utilizing minimum or maximum order constraints, the following changes need to be made to the CheckOrderFulfillabilityResponse in the booking server by the partner:

  • ItemFulfillabilityResult should be set to TICKET_CONSTRAINT_VIOLATED for the LineItemFulfillability
  • In the ‘LineItemFulfillability’ message, return one or more instances of the ‘violated_ticket_constraint’ message based on the relevant use-case.This will be a repeated field.
  • OrderFulfillabilityResult will be set to UNFULFILLABLE_LINE_ITEM within OrderFulfillability Below is the schema of representing the constraint within the ‘LineItemFulfillability’ message

Below is the schema of the ‘violated_ticket_constraint’ message

message ViolatedTicketConstraint {
    oneOf value {
      int32 min_ticket_count = 1;
      int32 max_ticket_count = 2;
    }
    // This is an optional field. The presence of this indicates
    //that the constraint applies specifically to a ticket-type.
   string ticket_id = 4;
  }
}

Specifying a minimum or maximum for the entire line item

Use this method if you want to implement a constraint on the total number of tickets purchased in a single line item (across ticket-types) within an order.

For example, if there is a broadway show that requires a minimum of two tickets (regardless of type), and there are 3 ticket types available (child, adult, or senior), then the line item level approach is the recommended method. Note: Do not include the ticket_type_id field for the minimum or maximum to apply to the entire line item.

In the example below, the user is trying to purchase just one adult ticket, but the minimum required (amongst any ticket type) is 2.

{
  "fulfillability": {
    "result": "UNFULFILLABLE_LINE_ITEM",
    "item_fulfillability": [
      {
        "item": {
          "service_id": "broadway_show",
          "start_sec": "1567000800",
          "duration_sec": "7200",
          "tickets": [
            {
              "ticket_id": "adult",
              "count": 1
            }
          ],
          "price": {
            "price_micros": "3000000",
            "currency_code": "USD"
          }
        },
        "result": "TICKET_CONSTRAINT_VIOLATED",
        "violated_ticket_constraint": [{
          "min_ticket_count": 2
        }]
      }
    ]
  }
}

Specifying a minimum or maximum for a ticket type within a line item

Use this method if the requested line item does not meet specific ticket type minimum or maximum. You are able to specify the specific ticket type(s) that have had their minimum or maximum not met as separate constraints.

In the example below of a parasailing service, there must be at least one person flying in order to book the service. In the example below the user is attempting to book an observer ticket (someone who rides on the boat watching) without booking at least one person flying.

{
  "fulfillability": {
    "result": "UNFULFILLABLE_LINE_ITEM",
    "item_fulfillability": [
      {
        "item": {
          "service_id": "parasailing",
          "start_sec": "1567000800",
          "duration_sec": "7200",
          "tickets": [
            {
              "ticket_id": "observer",
              "count": 1
            }
          ],
          "price": {
            "price_micros": "3000000",
            "currency_code": "USD"
          }
        },
        "result": "TICKET_CONSTRAINT_VIOLATED",
        "violated_ticket_constraint": [{
          "min_ticket_count": 1,
          "ticket_id": "flier"
        }]
      }
    ]
  }
}

Specifying a minimum or maximum for the entire line item as well as specific ticket types

If a service has a ticket type constraint as well as an overall line item constraint, you are able to specify both within your CheckOrderFulfillability response. In the example below the user is trying to purchase the V.I.P. addon pass without the general admission pass (ticket type level minimum not met). In addition this line item requires at least 2 tickets to be purchased (line item level minimum not met). Using the response below allows the user to see both of the actionable constraints for this order.

{
  "fulfillability": {
    "result": "UNFULFILLABLE_LINE_ITEM",
    "item_fulfillability": [
      {
        "item": {
          "service_id": "museum",
          "start_sec": "1567000800",
          "duration_sec": "7200",
          "tickets": [
            {
              "ticket_id": "vip-addon-pass",
              "count": 1
            }
          ],
          "price": {
            "price_micros": "3000000",
            "currency_code": "USD"
          }
        },
        "result": "TICKET_CONSTRAINT_VIOLATED",
        "violated_ticket_constraint": [{
          "min_ticket_count": 1,
          "ticket_id": "general-admission"
        },
        {
          "min_ticket_count": 2
        }]
      }
    ]
  }
}

Requirements for use

In order for the ‘violated_ticket_constraint’ message returned to be considered valid it must meet all of the below criteria. Should any of these criteria not be met the user will be shown a generic error message.

  1. A partner must return a positive value for the fields of min_ticket_count and max_ticket_count. Only one value can be sent at a time as per the schema.
  2. The ‘ticket_id’ mentioned in the constraint must belong to a valid “ticket_type” within the service or to a “ticket_type” within the availability slot if there is an override.
  3. There must be only one constraint that applies to the entire line item. The below example is invalid since there are two constraints that apply to the entire line item.
    {
    "fulfillability": {
    ..
    ..
        "result": "TICKET_CONSTRAINT_VIOLATED",
        "violated_ticket_constraint": [{
          "min_ticket_count": 2
        },
        {
          "min_ticket_count": 4
        }
        ]
    }
    }
    
  4. There must be only one constraint applied to a specific ticket type within the availability slot. The below example is invalid because there are two constraints applied to the “adult” ticket id. An individual ticket id can only have one constraint applied at a time.
    {
    "fulfillability": {
    ..
    ..
        "result": "TICKET_CONSTRAINT_VIOLATED",
        "violated_ticket_constraint": [{
          "ticket_id":"adult",
          "min_ticket_count": 2
        },
        {
          "ticket_id":"adult",
          "min_ticket_count": 4
        }
        ]
      }
    }