Tutorial: How to Structure Availability Using Ticket Types

Choosing an Availability Format

There are two ways to specify availability data using tickets: Pooled Availability or Per Ticket Availability. More than one method can be used concurrently, see Both Methods Concurrently

Use the following guide to help you determine which availability format is more suitable:

Parameter Definitions:

  • spots_open: The number of tickets currently available
  • spots_total: The total number of tickets that the merchant has for this configuration (including those that are not available)

Pooled Availability

Example

A theatre has 100 seats and sells 3 ticket types: Child, Adult, and Senior. Any seat can be filled by any ticket type.

Example 2

A zoo has capacity for 1000 people and sells 3 types of tickets based on age: Child, Adult, and Senior. Any number of any type of ticket can be sold until the zoo reaches capacity.

Let’s say a merchant is a Zoo and has capacity for 1,000 and offers 3 types of tickets (Adult, Child, and Senior). The daily feed snippet for services and availability (when no ticket has been purchased yet) is shown:

Feed Snippet

Service

"service": [
    {
      "name": "Zoo Visits",
      "service_id": "324560",
      "merchant_id": "283475",
      "prepayment_type": "REQUIRED",
      "require_credit_card": "REQUIRE_CREDIT_CARD_ALWAYS",
      "description": "Come to the Zoo to see all and learn more about all of your favorite animals!",
      "rules": {
        "min_advance_booking": 10800,
        "min_booking_buffer_before_end_time": null,
        "admission_policy": "TIME_STRICT"
      },
      "ticket_type": [
        {
          "short_description": "Adult Ticket",
          "price": {
            "price_micros": 195000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "1000"
        },
        {
          "short_description": "Child Ticket",
          "price": {
            "price_micros": 155000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "1001"
        },
        {
          "short_description": "Senior Ticket",
          "price": {
            "price_micros": 175000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "1002"
        }
      ],
    

Availability

"availability": [
  {
    "start_sec": 1534750200,
    "duration_sec": 28800,
    "spots_total": 1000,
    "service_id": "324560",
    "merchant_id": "283475",
    "spots_open": 1000
  },
  ]
    

In the example above, all 3 ticket types share the pool of 1000 spots_open. When any type of ticket is sold for the day, a real time update would lower the spots_open for this availability entry.

Per Ticket Availability

Example

A concert hall sells 50 backstage passes and 500 general admission tickets. In this case, the sale of a general admission ticket would not affect the number of backstage passes available, and the sale of a backstage pass would not affect the number of general admission tickets available. The daily feed snippet for services and availability (when no ticket has been purchased yet) is shown:

Feed Snippet

Service

"service": [
    {
      "name": "Musical Show",
      "service_id": "324560",
      "merchant_id": "283475",
      "prepayment_type": "REQUIRED",
      "require_credit_card": "REQUIRE_CREDIT_CARD_ALWAYS",
      "description": "Musician live in concert.",
      "rules": {
        "min_advance_booking": 10800,
        "min_booking_buffer_before_end_time": null,
        "admission_policy": "TIME_STRICT"
      },
      "ticket_type": [
        {
          "short_description": "Backstage Pass",
          "price": {
            "price_micros": 195000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "3005"
        },
        {
          "short_description": "General Admission",
          "price": {
            "price_micros": 155000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "2006"
        }
      ],
    

Availability

"availability": [
  {
    "ticket_type_id": [
      "3005"
    ],
    "start_sec": 1534750200,
    "duration_sec": 28800,
    "spots_total": 50,
    "service_id": "324560",
    "merchant_id": "283475",
    "spots_open": 50
  },
  {
    "ticket_type_id": [
      "2006"
    ],
    "start_sec": 1534750200,
    "duration_sec": 28800,
    "spots_total": 500,
    "service_id": "324560",
    "merchant_id": "283475",
    "spots_open": 500
  },
  ]
    

In the example above, the Backstage Passes and General Admission tickets are defined separately but for the same service at the same time. This allows them to be listed for the same service at the same time but have their availability controlled separately.

Using Both Methods Concurrently

Example

A concert hall sells Adult and Child backstage passes that share one pool of availability. The concert hall also sells Adult and Child general admission tickets that share a different pool. The daily feed snippet for services and availability (when no ticket has been purchased yet) is shown:

Feed Snippet

Service

"service": [
    {
      "name": "Musical Show",
      "service_id": "324560",
      "merchant_id": "283475",
      "prepayment_type": "REQUIRED",
      "require_credit_card": "REQUIRE_CREDIT_CARD_ALWAYS",
      "description": "Musicians live in concert.",
      "rules": {
        "min_advance_booking": 10800,
        "min_booking_buffer_before_end_time": null,
        "admission_policy": "TIME_STRICT"
      },
      "ticket_type": [
        {
          "short_description": "Adult Backstage Pass",
          "price": {
            "price_micros": 195000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "3005"
        },
       {
          "short_description": "Child Backstage Pass",
          "price": {
            "price_micros": 190000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "3006"
        },
        {
          "short_description": "Adult General Admission",
          "price": {
            "price_micros": 155000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "2006"
        },
        {
          "short_description": "Child General Admission",
          "price": {
            "price_micros": 150000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "2007"
        }
      ],
    

Availability

"availability": [
  {
    "ticket_type_id": [
      "3005",
      "3006"
    ],
    "start_sec": 1534750200,
    "duration_sec": 28800,
    "spots_total": 50,
    "service_id": "324560",
    "merchant_id": "283475",
    "spots_open": 50
  },
  {
    "ticket_type_id": [
      "2006",
      "2007"
    ],
    "start_sec": 1534750200,
    "duration_sec": 28800,
    "spots_total": 500,
    "service_id": "324560",
    "merchant_id": "283475",
    "spots_open": 500
  },
  ]
    

Different Pricing Based on Slot

Example

Ticket pricing is not always the same across all availability instances. For example, a zoo may have higher ticket prices on weekends. Additional ticket types with different prices should be modeled, and availability information should be provided for the corresponding ticket type for a given slot. The feeds below highlight the service and availability feed specifications for both weekday and weekend tickets that have differing prices:

Feed Snippet

Service

"service": [
    {
      "name": "Zoo Visits",
      "service_id": "324560",
      "merchant_id": "283475",
      "prepayment_type": "REQUIRED",
      "require_credit_card": "REQUIRE_CREDIT_CARD_ALWAYS",
      "description": "Come to the Zoo to see all and learn more about all of your favorite animals!",
      "rules": {
        "min_advance_booking": 10800,
        "min_booking_buffer_before_end_time": null,
        "admission_policy": "TIME_STRICT"
      },
      "ticket_type": [
        {
          "short_description": "Adult Ticket",
          "price": {
            "price_micros": 195000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "1000"
        },
        {
          "short_description": "Adult Ticket",
          "price": {
            "price_micros": 205000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "1000-1"
        },
        {
          "short_description": "Child Ticket",
          "price": {
            "price_micros": 155000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "1001"
        },
        {
          "short_description": "Child Ticket",
          "price": {
            "price_micros": 165000000,
            "currency_code": "USD"
          },
          "ticket_type_id": "1001-1"
        }
      ],
    

Availability

"availability": [
  {
    "ticket_type_id": [
      "1000",
      "1001"
    ],
    "start_sec": 1534750200,
    "duration_sec": 28800,
    "spots_total": 1000,
    "service_id": "324560",
    "merchant_id": "283475",
    "spots_open": 1000
  },
  {
    "ticket_type_id": [
      "1000-1",
      "1001-1"
    ],
    "start_sec": 1534660200,
    "duration_sec": 28800,
    "spots_total": 1000,
    "service_id": "324560",
    "merchant_id": "283475",
    "spots_open": 1000
  }
  ]