Quantities

When customers select a ticket holder, there may be limits on bookable quantities. These limits may exist for both the timeslot and the ticket holder (formally known as the product). Both sets of limits should be observed in order to provide a smooth customer experience.

Timeslot

At the timeslot level, quantity limits restrict the total number of products which can be added to cart for that specific date/time. There are three properties which describe a timeslot's quantity limits.

max_buy

This property is the maximum quantity you are allowed to add to cart for the timeslot. Its value is based on sales restrictions (if any) and remaining seats from the availability property.

When the value is zero, the timeslot is no longer available and its products cannot be added to cart.

When the value is greater than zero, the total quantity for products added to cart must be less than or equal to this value.

A value of -1 means the timeslot has no maximum quantity requirement.

min_buy

This property is the minimum quantity a timeslot must have if you want to add to cart. The total quantity for products added to cart must be greater than or equal to this value.

A value of -1 means the timeslot has no minimum quantity requirement.

availability

While min_buy and max_buy impose quantity limits for the timeslot, the availability property displays the total number of remaining seats for the timeslot.

A value of -1 means the number of remaining seats has not been specified for the timeslot.

Ticket holder (product)

At the ticket holder level (formally known as the product), quantity limits apply to the specific product you want to add to cart. These may differ from the timeslot restrictions. There are three properties which describe a product's quantity limits.

max_buy

This property refers to the maximum quantity of a product you are allowed to add to cart. Its value is based on sales restrictions (if any) and remaining seats from the availability property.

When the value is zero, then the product is no longer available and cannot be added to cart.

When the value is greater than zero, the total quantity for products added to cart must be less than or equal to this value.

min_buy

This property refers to the minimum quantity a product must have if you want to add it to cart.

availability

While min_buy and max_buy impose quantity limits, the availability property refers to the number of remaining seats for an individual product.

A value of -1 means the number of remaining seats has not been specified for the product.

Examples

Timeslot with limits

In the example response below, the timeslot has no specified minimum and permits a maximum of 20 seats:

{
	"groups": [
		{
			[...]
			"slots": [
				{
					[...]
					"min_buy": -1,
					"max_buy": 20,
					"availability": 20,
					"products": [
						{
							[...]
							"name": "Adult (8+)",
							"min_buy": 1,
							"max_buy": 15,
							"availability": -1,
							[...]
						},
						{
							[...]
							"name": "Child (3-7)",
							"min_buy": 1,
							"max_buy": 15,
							"availability": -1,
							[...]
						}
					]
				}
			]
		}
	]
}

In the same example, the number of remaining seats per product is not specified. Customers can add any combination of the product quantities, provided their total quantity is not more than 20 and their individual quantities are not more than 15.

Timeslot with no limits

In the example response below, there are no timeslot limits and the one available product requires a quantity of at least two in order to be added to cart:

{
	"groups": [
		{
			[...]
			"slots": [
				{
					[...]
					"min_buy": -1,
					"max_buy": -1,
					"availability": -1,
					"products": [
						{
							[...]
							"min_buy": 2,
							"max_buy": 12,
							"availability": 12,
							[...]
						}
					]
				}
			]
		}
	]
}

In the same example, while there is no maximum for the timeslot, the product imposes a maximum of 12. Any attempt to add a quantity greater than 12 will fail.