# Atom Tickets Partner API — Complete Reference

> Full API specification for AI agents and automation systems integrating with Atom Tickets.
> This document contains every endpoint, parameter, request/response example, and data model
> from the official documentation. An AI agent can build a complete API client from this alone.

---

## Authentication

All API requests require authentication via HTTP headers.

| Header           | Value                                                | Required |
| ---------------- | ---------------------------------------------------- | -------- |
| `x-api-key`      | API key provided by Atom Tickets                     | **Yes**  |
| `X-Atom-Partner` | Agreed upon value per partner for specific use cases | No       |
| `Content-Type`   | `application/json` (required for POST requests)      | POST only|

The `X-Atom-Partner` header value is agreed upon during partner onboarding. Some endpoints may require it for partner-specific behavior.

---

## Environments

| Stage     | Base URL                            |
| --------- | ----------------------------------- |
| **Beta**  | `https://api-beta.atomtickets.com`  |
| **Prod**  | `https://api.atomtickets.com`       |

Use the **Beta** environment for development and testing. Production endpoints and rate limits are determined during partner onboarding.

All API routes are prefixed with `/partner/`. Versioned endpoints use `/partner/v1/`.

---

## Rate Limits

| Environment                | Rate Limit                                            |
| -------------------------- | ----------------------------------------------------- |
| **Testing** (Beta)         | 25 requests/sec baseline with a 50 requests/sec burst |
| **Production**             | Negotiated between Atom Tickets and the partner       |

If you exceed the rate limit, the API returns HTTP **429 Too Many Requests**. Implement exponential backoff to handle this gracefully.

### Best Practices

- **Cache responses** where possible — venue and production details don't change frequently
- **Use batch endpoints** (e.g., `byIds`) to fetch multiple resources in a single request
- **Use the `forVenues` endpoint** to fetch showtimes for multiple venues at once
- **Limit page sizes** to what you actually need rather than requesting the maximum of 100

---

## Value Defaults and Limits

| Field                            | Default | Max    |
| -------------------------------- | ------- | ------ |
| `radius`                         | —       | 80km   |
| `pageSize`                       | 25      | 100    |
| `startDate`/`endDate` difference | 1 day   | 7 days |

---

## Date Formats

The API supports two date format styles. When an endpoint accepts date ranges, you must provide **either** the ISO pair **or** the local pair — not both.

**ISO 8601 (with timezone):**
```
isoStartDate=2024-01-15T07:00:00Z
isoEndDate=2024-01-16T07:00:00Z
```

**Local date (no timezone):**
```
localStartDate=2024-01-15T00:00:00
localEndDate=2024-01-16T00:00:00
```

---

## ID Formats

- Venue IDs start with `C` (e.g., `C0057070265`)
- Production IDs start with `B` (e.g., `B00879153184`)
- Showtime IDs start with `D` (e.g., `D00747321039`)

---

## Integration / Checkout Flow

1. Search venues -> get `venueId`
2. Get production IDs at venue -> get production `ids`
3. Get production details by IDs -> get full movie info
4. Get showtimes at venue -> get `showtimeId` and `checkoutUrl`
5. Redirect user to `checkoutUrl` for ticket purchase

The checkout URL format:
```
https://rw.atomtickets.com/checkout/redirect?productionId={id}&venueId={id}&localShowtime={datetime}&iref=atomapi
```

---

# ENDPOINTS

---

## 1. GET /partner/ping

Health check. Verify your API key and that the service is running.

**Note:** This endpoint does NOT use the `/v1/` prefix. The route is `/partner/ping`.

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/partner/ping' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns **HTTP 200** with no response body if the health check is successful.

---

## 2. GET /partner/v1/venue/details/byLocation

Search for venues near a geographic point.

### Parameters

| Parameter  | Type     | Required | Description                              |
| ---------- | -------- | -------- | ---------------------------------------- |
| `lat`      | `Double` | Yes      | Latitude                                 |
| `lon`      | `Double` | Yes      | Longitude                                |
| `radius`   | `Double` | Yes      | Search radius in km (max 80)             |
| `page`     | `Int`    | No       | Page number                              |
| `pageSize` | `Int`    | No       | Results per page (default: 25, max: 100) |

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/partner/v1/venue/details/byLocation?lat=34.0195&lon=-118.4912&radius=50&pageSize=2' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `VenueDetailsResponse` ordered by distance from the provided coordinates.

```json
{
  "venueDetails": [
    {
      "venue": {
        "id": "C00110921804",
        "name": "AMC Loews Broadway 4",
        "address": {
          "line": "1441 Third Street Promenade",
          "city": "Santa Monica",
          "state": "CA",
          "postal": "90401",
          "lat": 34.014801025390625,
          "lon": -118.49500274658203
        },
        "properties": {
          "supportsConcessions": true,
          "supported": true
        },
        "venueUrl": "http://rw-beta.atomtickets.com/theaters/redirect/C00110921804",
        "atomVenueId": "1341"
      },
      "kmDistance": 0.628527332801801
    },
    {
      "venue": {
        "id": "C00401723167",
        "name": "AMC Santa Monica 7",
        "address": {
          "line": "1310 3rd Street",
          "city": "Santa Monica",
          "state": "CA",
          "postal": "90401",
          "lat": 34.016693115234375,
          "lon": -118.49755859375
        },
        "properties": {
          "supportsConcessions": true,
          "supported": true
        },
        "venueUrl": "http://rw-beta.atomtickets.com/theaters/redirect/C00401723167",
        "atomVenueId": "44608"
      },
      "kmDistance": 0.6647355560508852
    }
  ],
  "pageInfo": {
    "page": 1,
    "pageSize": 2,
    "totalPages": 52
  }
}
```

---

## 3. POST /partner/v1/venue/details/byIds

Look up specific venues by their IDs.

### Request Body — `GetVenueDetailsRequest`

| Field      | Type           | Required | Description                                                |
| ---------- | -------------- | -------- | ---------------------------------------------------------- |
| `ids`      | `List[String]` | Yes      | List of venue IDs to look up                               |
| `location` | `LatLonPair`   | No       | If provided, response includes `kmDistance` for each venue |
| `page`     | `Int`          | No       | Page number for pagination                                 |
| `pageSize` | `Int`          | No       | Items per page (default: 25, max: 100)                     |

### Request

```bash
curl -X POST \
  https://api-beta.atomtickets.com/partner/v1/venue/details/byIds \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "ids": ["C0057070265"],
    "location": {
      "lat": 34.0195,
      "lon": -118.4912
    }
  }'
```

### Response

Returns `VenueDetailsResponse`. If a `location` is provided in the request, each venue includes `kmDistance`.

```json
{
  "venueDetails": [
    {
      "venue": {
        "id": "C0057070265",
        "name": "Regal LA Live & 4DX",
        "address": {
          "line": "1000 West Olympic Boulevard",
          "city": "Los Angeles",
          "state": "CA",
          "postal": "90015",
          "lat": 34.031402587890625,
          "lon": -118.46971130371094
        },
        "properties": {
          "supportsConcessions": false,
          "supported": false
        },
        "venueUrl": "http://rw-beta.atomtickets.com/theaters/redirect/C0057070265",
        "atomVenueId": "20263"
      },
      "kmDistance": 2.383671824436259
    }
  ]
}
```

---

## 4. GET /partner/v1/venue/details/search

Search for venues matching a text query within a geographic area.

### Parameters

| Parameter  | Type     | Required | Description                  |
| ---------- | -------- | -------- | ---------------------------- |
| `term`     | `String` | Yes      | Search query for venue names |
| `lat`      | `Double` | Yes      | Latitude                     |
| `lon`      | `Double` | Yes      | Longitude                    |
| `radius`   | `Double` | Yes      | Search radius in km (max 80) |
| `pageSize` | `Int`    | No       | Results per page             |
| `page`     | `Int`    | No       | Page number                  |

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/partner/v1/venue/details/search?term=amc&lat=34.0195&lon=-118.4912&radius=50&pageSize=2' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `VenueDetailsResponse` ordered by distance from the provided coordinates.

```json
{
  "venueDetails": [
    {
      "venue": {
        "id": "C00110921804",
        "name": "AMC Loews Broadway 4",
        "address": {
          "line": "1441 Third Street Promenade",
          "city": "Santa Monica",
          "state": "CA",
          "postal": "90401",
          "lat": 34.014801025390625,
          "lon": -118.49500274658203
        },
        "properties": {
          "supportsConcessions": true,
          "supported": true
        },
        "venueUrl": "http://rw-beta.atomtickets.com/theaters/redirect/C00110921804",
        "atomVenueId": "1341"
      },
      "kmDistance": 0.628527332801801
    },
    {
      "venue": {
        "id": "C00401723167",
        "name": "AMC Santa Monica 7",
        "address": {
          "line": "1310 3rd Street",
          "city": "Santa Monica",
          "state": "CA",
          "postal": "90401",
          "lat": 34.016693115234375,
          "lon": -118.49755859375
        },
        "properties": {
          "supportsConcessions": true,
          "supported": true
        },
        "venueUrl": "http://rw-beta.atomtickets.com/theaters/redirect/C00401723167",
        "atomVenueId": "11729"
      },
      "kmDistance": 0.6647355560508852
    }
  ],
  "pageInfo": {
    "page": 1,
    "pageSize": 2,
    "totalPages": 10
  }
}
```

---

## 5. GET /partner/v1/venues/byVendorVenueId/{vendorVenueId}

Look up an Atom venue using your internal vendor venue ID. Useful for mapping your system's venue IDs to Atom's.

### Path Parameters

| Parameter       | Type     | Required | Description                    |
| --------------- | -------- | -------- | ------------------------------ |
| `vendorVenueId` | `String` | Yes      | Your internal venue identifier |

### Query Parameters

| Parameter   | Type     | Required | Description                               |
| ----------- | -------- | -------- | ----------------------------------------- |
| `circuitId` | `String` | No       | Limit query to a specific theater circuit |

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/partner/v1/venues/byVendorVenueId/0001' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `VenueDetailsResponse`.

```json
{
  "venueDetails": [
    {
      "venue": {
        "id": "C00889608713",
        "name": "Flix Brewhouse - Des Moines",
        "address": {
          "line": "3800 Merle Hay Road",
          "city": "Des Moines",
          "state": "IA",
          "postal": "50310",
          "lat": 41.629539489746094,
          "lon": -93.69798278808594
        },
        "properties": {
          "supportsConcessions": true,
          "supported": true
        },
        "venueUrl": "http://rw-beta.atomtickets.com/theaters/redirect/C00889608713",
        "atomVenueId": "7364"
      }
    }
  ]
}
```

---

## 6. GET /partner/v1/production/ids/byVenue/{venueId}

Get a list of production IDs currently playing at a venue within a date range. Returns IDs only (not full details). Results are ordered by Atom Meter (popularity).

### Path Parameters

| Parameter | Type     | Required | Description      |
| --------- | -------- | -------- | ---------------- |
| `venueId` | `String` | Yes      | Venue identifier |

### Query Parameters

Provide **either** ISO dates **or** local dates:

| Parameter        | Type     | Required | Description                                        |
| ---------------- | -------- | -------- | -------------------------------------------------- |
| `isoStartDate`   | `String` | Yes*     | ISO 8601 start date (e.g., `2024-01-15T07:00:00Z`) |
| `isoEndDate`     | `String` | Yes*     | ISO 8601 end date                                  |
| `localStartDate` | `String` | Yes*     | Local start date (`YYYY-MM-DDTHH:MM:SS`)           |
| `localEndDate`   | `String` | Yes*     | Local end date                                     |
| `marketplaceId`  | `String` | No       | Marketplace filter                                 |

*Provide either the ISO pair or the local pair, not both.

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/partner/v1/production/ids/byVenue/C00110921804?isoStartDate=2019-10-10T07:00:00Z&isoEndDate=2019-10-11T07:00:00Z' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `ProductionIdsResponse`.

```json
{
  "ids": ["B0093420570", "B00437681129", "B00685932020", "B00309261556"]
}
```

---

## 7. POST /partner/v1/production/details/byIds

Fetch full details for specific productions.

### Request Body — `GetProductionDetailsRequest`

| Field           | Type           | Required | Description                            |
| --------------- | -------------- | -------- | -------------------------------------- |
| `ids`           | `List[String]` | Yes      | List of production IDs to look up      |
| `marketplaceId` | `String`       | No       | Marketplace filter (defaults to US)    |
| `page`          | `Int`          | No       | Page number for pagination             |
| `pageSize`      | `Int`          | No       | Items per page (default: 25, max: 100) |

### Request

```bash
curl -X POST \
  https://api-beta.atomtickets.com/partner/v1/production/details/byIds \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "ids": ["B00809994585"]
  }'
```

### Response

Returns `ProductionDetailsResponse`.

```json
{
  "productionDetails": [
    {
      "id": "B00809994585",
      "name": "The Predator",
      "productionMedia": {
        "imageData": {
          "coverImageUrl": "https://images.atomtickets.com/image/upload/w_520,h_780,q_auto/v1/ingestion-images-archive/archive/rm3117827584.jpg",
          "promoImageUrls": [
            "https://images.atomtickets.com/image/upload/h_960,q_auto/v1526062779/ingestion-images-archive/archive/1526062778201_227902_cops_1.png"
          ]
        },
        "trailerData": {
          "trailerUrls": []
        }
      },
      "contributors": {
        "cast": [
          {
            "name": "Boyd Holbrook",
            "characterName": "Quinn McKenna"
          }
        ],
        "crew": [
          {
            "name": "Shane Black",
            "role": "Director"
          }
        ]
      },
      "synopsis": "When a young boy accidentally triggers the universe's most lethal hunters return to Earth, only a ragtag crew of ex-soldiers and a disgruntled science teacher can prevent the end of the human race.",
      "advisoryRating": "No Rating",
      "genres": ["Action", "Adventure", "Horror", "Sci-Fi", "Thriller"],
      "runtimeMinutes": 0,
      "releaseDate": "2018-09-14",
      "atomUserScore": 10.0,
      "productionUrl": "http://rw-beta.atomtickets.com/movies/redirect/B00809994585",
      "imdbId": "3829266",
      "atomProductionId": "227902"
    }
  ]
}
```

---

## 8. GET /partner/v1/production/search/byName

Search for productions matching a name query.

### Parameters

| Parameter | Type     | Required | Description                   |
| --------- | -------- | -------- | ----------------------------- |
| `name`    | `String` | Yes      | Production name to search for |

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/partner/v1/production/search/byName?name=Captain%20Marvel' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `ProductionDetailsResponse`.

```json
{
  "productionDetails": [
    {
      "id": "B00362154100",
      "name": "Captain Marvel",
      "productionMedia": {
        "imageData": {
          "coverImageUrl": "https://images.atomtickets.com/image/upload/w_520,h_780,q_auto/v1/ingestion-images-archive/archive/rm123368960.jpg",
          "promoImageUrls": []
        },
        "trailerData": {
          "trailerUrls": [
            "https://www.totaleclips.com/Bounce/b?eclipid=e162647&bitrateid=449&vendorid=17871"
          ]
        }
      },
      "contributors": {
        "cast": [
          {
            "name": "Brie Larson",
            "characterName": "Carol Danvers, Vers, Captain Marvel"
          }
        ],
        "crew": [
          {
            "name": "Anna Boden",
            "role": "Director"
          }
        ]
      },
      "synopsis": "The story follows Carol Danvers as she becomes one of the universe's most powerful heroes when Earth is caught in the middle of a galactic war between two alien races. Set in the 1990s, Captain Marvel is an all-new adventure from a previously unseen period in the history of the Marvel Cinematic Universe.",
      "advisoryRating": "PG-13",
      "genres": ["Action/Adventure", "SciFi/Fantasy"],
      "runtimeMinutes": 124,
      "releaseDate": "2019-03-08",
      "atomUserScore": 6.7,
      "productionUrl": "http://rw-beta.atomtickets.com/movies/redirect/B00362154100",
      "imdbId": "4154664"
    }
  ]
}
```

---

## 9. GET /partner/v1/productions/byVendorProductionId/{vendorProductionId}

Look up an Atom production using your internal vendor production ID.

### Path Parameters

| Parameter            | Type     | Required | Description                         |
| -------------------- | -------- | -------- | ----------------------------------- |
| `vendorProductionId` | `String` | Yes      | Your internal production identifier |

### Query Parameters

| Parameter   | Type     | Required | Description                       |
| ----------- | -------- | -------- | --------------------------------- |
| `circuitId` | `String` | No       | Limit query to a specific circuit |

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/partner/v1/productions/byVendorProductionId/0000001176' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `ProductionDetailsResponse`.

```json
{
  "productionDetails": [
    {
      "id": "B00849252296",
      "name": "The Last Movie",
      "productionMedia": {
        "imageData": {
          "coverImageUrl": "https://images.atomtickets.com/image/upload/w_520,h_780,q_auto/v1/ingestion-images-archive/archive/rm1217998848.jpg",
          "promoImageUrls": []
        },
        "trailerData": {
          "trailerUrls": [
            "https://www.totaleclips.com/Bounce/b?eclipid=e164394&bitrateid=449&vendorid=17871"
          ]
        }
      },
      "contributors": {
        "cast": [
          {
            "name": "Julie Adams",
            "characterName": "Mrs. Anderson"
          }
        ],
        "crew": [
          {
            "name": "Dennis Hopper",
            "role": "Director"
          }
        ]
      },
      "synopsis": "The Last Movie follows a Hollywood movie crew in the midst of making a western in a remote Peruvian village...",
      "advisoryRating": "R",
      "genres": ["Drama"],
      "runtimeMinutes": 108,
      "releaseDate": "2018-08-03",
      "productionUrl": "http://rw-beta.atomtickets.com/movies/redirect/B00849252296",
      "imdbId": "5836316"
    }
  ]
}
```

---

## 10. GET /partner/v1/showtime/details/byVenue/{venueId}

Get all showtimes at a specific venue within a date range.

### Path Parameters

| Parameter | Type     | Required | Description      |
| --------- | -------- | -------- | ---------------- |
| `venueId` | `String` | Yes      | Venue identifier |

### Query Parameters

Provide **either** ISO dates **or** local dates:

| Parameter        | Type     | Required | Description                                         |
| ---------------- | -------- | -------- | --------------------------------------------------- |
| `isoStartDate`   | `String` | Yes*     | ISO 8601 start date                                 |
| `isoEndDate`     | `String` | Yes*     | ISO 8601 end date                                   |
| `localStartDate` | `String` | Yes*     | Local start date                                    |
| `localEndDate`   | `String` | Yes*     | Local end date                                      |
| `productionIds`  | `String` | No       | Comma-separated list of production IDs to filter by |

*Provide either the ISO pair or the local pair, not both.

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/partner/v1/showtime/details/byVenue/C00110921804?isoStartDate=2018-09-14T07:00:00Z&isoEndDate=2018-09-15T07:00:00Z' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `ShowtimeDetailsResponse` including pre-order details and an attribute map.

```json
{
  "showtimeDetails": [
    {
      "showtimeId": "D00747321039",
      "productionId": "B00879153184",
      "venueId": "C0057070265",
      "offerData": {
        "offers": [
          {
            "label": "Ticket",
            "price": { "value": 12.75, "currencyCode": "USD" }
          }
        ]
      },
      "utcShowtimeStart": "2018-09-14T20:30:00Z",
      "localShowtimeStart": "2018-09-14T13:30:00-07:00",
      "attributes": ["STADIUM-SEATING", "CC"]
    },
    {
      "showtimeId": "D00383546016",
      "productionId": "B00651431218",
      "venueId": "C0057070265",
      "offerData": {
        "offers": [
          {
            "label": "Matinee",
            "price": { "value": 14, "currencyCode": "USD" }
          },
          { "label": "Child", "price": { "value": 13, "currencyCode": "USD" } },
          { "label": "Senior", "price": { "value": 13, "currencyCode": "USD" } }
        ]
      },
      "utcShowtimeStart": "2018-09-14T20:40:00Z",
      "localShowtimeStart": "2018-09-14T13:40:00-07:00",
      "attributes": ["CC", "DV", "STADIUM-SEATING", "RESERVED"]
    }
  ],
  "preOrderDetails": [
    {
      "productionId": "B00856886544",
      "venueId": "C0057070265",
      "showtimeDays": ["2018-10-06T00:00:00-07:00"]
    },
    {
      "productionId": "B00775577087",
      "venueId": "C0057070265",
      "showtimeDays": [
        "2018-09-25T00:00:00-07:00",
        "2018-09-26T00:00:00-07:00",
        "2018-09-27T00:00:00-07:00",
        "2018-09-29T00:00:00-07:00",
        "2018-10-02T00:00:00-07:00"
      ]
    }
  ],
  "attributeMap": {
    "RESERVED": {
      "id": "RESERVED",
      "iconUrl": "https://images.atomtickets.com/image/upload/q_auto/v1/client-image-repo/attributes/RESERVED_V2_1517873333535.png",
      "friendlyName": "Reserved Seating",
      "description": "Description"
    }
  }
}
```

---

## 11. POST /partner/v1/showtime/details/byIds

Look up specific showtimes by their IDs. The response includes `checkoutUrl` and `availableInventory` for each showtime.

### Request Body — `GetShowtimeDetailsRequest`

| Field      | Type           | Required | Description                            |
| ---------- | -------------- | -------- | -------------------------------------- |
| `ids`      | `List[String]` | Yes      | List of showtime IDs to look up        |
| `page`     | `Int`          | No       | Page number                            |
| `pageSize` | `Int`          | No       | Items per page (default: 25, max: 100) |

### Request

```bash
curl -X POST \
  https://api-beta.atomtickets.com/partner/v1/showtime/details/byIds \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "ids": ["D00776442169"]
  }'
```

### Response

Returns `ShowtimeDetailsResponse`.

```json
{
  "showtimeDetails": [
    {
      "showtimeId": "D00776442169",
      "productionId": "B00418470916",
      "venueId": "C0057070265",
      "offerData": { "offers": [] },
      "utcShowtimeStart": "2018-09-12T20:30:00Z",
      "localShowtimeStart": "2018-09-12T13:30:00-07:00",
      "attributes": ["STADIUM-SEATING", "CC"],
      "checkoutUrl": "http://rw-beta.atomtickets.com/checkout/redirect?productionId=B00418470916&venueId=C0057070265&localShowtime=2018-09-12T13:30:00&iref=atomapi",
      "availableInventory": 1
    }
  ],
  "preOrderDetails": [],
  "attributeMap": {
    "STADIUM-SEATING": {
      "id": "STADIUM-SEATING",
      "type": "SECONDARY",
      "iconUrl": "https://images.atomtickets.com/image/upload/q_auto/v1/client-image-repo/attributes/STADIUM-SEATING_V2_1517873031977.png",
      "friendlyName": "Stadium seating",
      "description": "Stadium seating."
    },
    "CC": {
      "id": "CC",
      "type": "SECONDARY",
      "iconUrl": "https://images.atomtickets.com/image/upload/q_auto/v1/client-image-repo/attributes/CC_V2_1517872363908.png",
      "friendlyName": "CC",
      "description": "Closed Captioning devices display a movie's dialogue and sound effects as text; captions are not shown on the main screen. Devices available by request."
    }
  }
}
```

---

## 12. POST /partner/v1/showtime/details/forVenues

Batch-query showtimes across multiple venues. Optionally include full production details in the response.

### Request Body — `GetShowtimesForVenuesRequest`

| Field                      | Type             | Required | Description                                         |
| -------------------------- | ---------------- | -------- | --------------------------------------------------- |
| `venueIds`                 | `Set[String]`    | Yes      | Set of venue IDs to query                           |
| `productionIds`            | `Set[String]`    | No       | Filter to specific productions                      |
| `isoDateBounds`            | `ISODateBounds`  | No*      | Date range (ISO 8601)                               |
| `localDateBounds`          | `LocalDateBounds`| No*      | Date range (local time)                             |
| `includeProductionDetails` | `Boolean`        | No       | If `true`, response includes `productionDetailsMap` |
| `marketplaceId`            | `String`         | No       | Marketplace filter                                  |

*Provide either `isoDateBounds` or `localDateBounds`, not both.

### Request

```bash
curl -X POST \
  https://api-beta.atomtickets.com/partner/v1/showtime/details/forVenues \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "venueIds": ["C0057070265", "C00110921804", "C00401723167"],
    "isoDateBounds": {
      "isoStartDate": "2019-02-25T07:00:00Z",
      "isoEndDate": "2019-02-26T07:00:00Z"
    },
    "includeProductionDetails": true
  }'
```

### Response

Returns `ShowtimeDetailsForVenuesResponse` with showtimes grouped by venue ID.

```json
{
  "venueShowtimeDetailsMap": {
    "C00110921804": {
      "showtimeDetails": [],
      "preOrderDetails": [
        {
          "productionId": "B00362154100",
          "venueId": "C00110921804",
          "showtimeDays": [
            "2019-03-07T00:00:00-08:00",
            "2019-03-08T00:00:00-08:00",
            "2019-03-09T00:00:00-08:00"
          ]
        }
      ]
    },
    "C00401723167": {
      "showtimeDetails": [
        {
          "showtimeId": "D00841132746",
          "productionId": "B00629445690",
          "venueId": "C00401723167",
          "offerData": { "offers": [] },
          "utcShowtimeStart": "2019-02-25T19:30:00Z",
          "localShowtimeStart": "2019-02-25T11:30:00-08:00",
          "attributes": ["RESERVED", "DVS"]
        },
        {
          "showtimeId": "D00877858635",
          "productionId": "B00629445690",
          "venueId": "C00401723167",
          "offerData": { "offers": [] },
          "utcShowtimeStart": "2019-02-25T22:00:00Z",
          "localShowtimeStart": "2019-02-25T14:00:00-08:00",
          "attributes": ["RESERVED", "DVS", "REALD3D"]
        }
      ],
      "preOrderDetails": [
        {
          "productionId": "B00178318857",
          "venueId": "C00401723167",
          "showtimeDays": ["2019-03-02T00:00:00-08:00"]
        }
      ]
    }
  },
  "attributeMap": {
    "DVS": {
      "id": "DVS",
      "iconUrl": "https://images.atomtickets.com/image/upload/q_auto/v1/client-image-repo/attributes/DVS_V2_1517871554190.png",
      "friendlyName": "Descriptive Video",
      "description": "Description"
    }
  },
  "productionDetailsMap": {
    "B00949090095": {
      "id": "B00949090095",
      "name": "Gone with the Wind 80th Anniversary",
      "productionMedia": {
        "imageData": {
          "coverImageUrl": "https://images.atomtickets.com/image/upload/ingestion-images-archive-prod/archive/coming_soon_poster.jpg",
          "promoImageUrls": []
        },
        "trailerData": { "trailerUrls": [] }
      },
      "contributors": { "cast": [], "crew": [] },
      "synopsis": "",
      "advisoryRating": "No Rating",
      "genres": [""],
      "runtimeMinutes": 0
    }
  }
}
```

---

## 13. GET /partner/v1/venues/{venueId}/showtimes/byVendorShowtimeId/{vendorShowtimeId}

Look up a showtime using your internal vendor showtime ID and an Atom venue ID.

### Path Parameters

| Parameter          | Type     | Required | Description                       |
| ------------------ | -------- | -------- | --------------------------------- |
| `venueId`          | `String` | Yes      | Atom venue identifier             |
| `vendorShowtimeId` | `String` | Yes      | Your internal showtime identifier |

### Query Parameters

| Parameter   | Type     | Required | Description                       |
| ----------- | -------- | -------- | --------------------------------- |
| `circuitId` | `String` | No       | Limit query to a specific circuit |

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/partner/v1/venues/C00682352378/showtimes/byVendorShowtimeId/19' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `ShowtimeDetailsResponse`. Includes `checkoutUrl` and `availableInventory`.

```json
{
  "showtimeDetails": [
    {
      "showtimeId": "D00999351728",
      "productionId": "B00849252296",
      "venueId": "C00682352378",
      "offerData": { "offers": [] },
      "utcShowtimeStart": "2019-09-13T20:05:00Z",
      "localShowtimeStart": "2019-09-13T16:05:00-04:00",
      "attributes": ["RESERVED"],
      "checkoutUrl": "http://rw-beta.atomtickets.com/checkout/redirect?productionId=B00849252296&venueId=C00682352378&localShowtime=2019-09-13T16:05:00&iref=atomapi",
      "availableInventory": 1
    }
  ],
  "preOrderDetails": [],
  "attributeMap": {
    "RESERVED": {
      "id": "RESERVED",
      "type": "SECONDARY",
      "iconUrl": "https://images.atomtickets.com/image/upload/q_auto/v1/client-image-repo/attributes/RESERVED_V2_1517873333535.png",
      "friendlyName": "Reserved Seating",
      "description": "This showtime features reserved seating so you can pick your seats ahead of time."
    }
  }
}
```

---

## 14. GET /partner/v1/venues/byVendorVenueId/{vendorVenueId}/showtimes/byVendorShowtimeId/{vendorShowtimeId}

Look up a showtime using both your internal vendor venue ID and vendor showtime ID.

### Path Parameters

| Parameter          | Type     | Required | Description                       |
| ------------------ | -------- | -------- | --------------------------------- |
| `vendorVenueId`    | `String` | Yes      | Your internal venue identifier    |
| `vendorShowtimeId` | `String` | Yes      | Your internal showtime identifier |

### Query Parameters

| Parameter   | Type     | Required | Description                       |
| ----------- | -------- | -------- | --------------------------------- |
| `circuitId` | `String` | No       | Limit query to a specific circuit |

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/partner/v1/venues/byVendorVenueId/511/showtimes/byVendorShowtimeId/19' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `ShowtimeDetailsResponse`. Includes `checkoutUrl` and `availableInventory`.

```json
{
  "showtimeDetails": [
    {
      "showtimeId": "D00999351728",
      "productionId": "B00849252296",
      "venueId": "C00682352378",
      "offerData": { "offers": [] },
      "utcShowtimeStart": "2019-09-13T20:05:00Z",
      "localShowtimeStart": "2019-09-13T16:05:00-04:00",
      "attributes": ["RESERVED"],
      "checkoutUrl": "http://rw-beta.atomtickets.com/checkout/redirect?productionId=B00849252296&venueId=C00682352378&localShowtime=2019-09-13T16:05:00&iref=atomapi",
      "availableInventory": 1
    }
  ],
  "preOrderDetails": [],
  "attributeMap": {
    "RESERVED": {
      "id": "RESERVED",
      "type": "SECONDARY",
      "iconUrl": "https://images.atomtickets.com/image/upload/q_auto/v1/client-image-repo/attributes/RESERVED_V2_1517873333535.png",
      "friendlyName": "Reserved Seating",
      "description": "This showtime features reserved seating so you can pick your seats ahead of time."
    }
  }
}
```

---

# DATA MODELS

---

## Common Models

### PageInfo

Pagination metadata included in list responses.

```typescript
PageInfo {
  page: Int,
  pageSize: Int,
  totalPages: Int
}
```

| Field        | Type  | Description                     |
| ------------ | ----- | ------------------------------- |
| `page`       | `Int` | Current page number             |
| `pageSize`   | `Int` | Number of items per page        |
| `totalPages` | `Int` | Total number of pages available |

### LatLonPair

Geographic coordinates used for location-based queries.

```typescript
LatLonPair {
  lat: Double,
  lon: Double
}
```

| Field | Type     | Description |
| ----- | -------- | ----------- |
| `lat` | `Double` | Latitude    |
| `lon` | `Double` | Longitude   |

### ISODateBounds

Date range using ISO 8601 formatted dates with timezone.

```typescript
ISODateBounds {
  isoStartDate: String,
  isoEndDate: String
}
```

| Field          | Type     | Description                                                  |
| -------------- | -------- | ------------------------------------------------------------ |
| `isoStartDate` | `String` | Start date in ISO 8601 format (e.g., `2024-01-15T07:00:00Z`) |
| `isoEndDate`   | `String` | End date in ISO 8601 format (e.g., `2024-01-16T07:00:00Z`)   |

### LocalDateBounds

Date range using local dates without timezone information.

```typescript
LocalDateBounds {
  localStartDate: String,
  localEndDate: String
}
```

| Field            | Type     | Description                                              |
| ---------------- | -------- | -------------------------------------------------------- |
| `localStartDate` | `String` | Start date in local format (e.g., `2024-01-15T00:00:00`) |
| `localEndDate`   | `String` | End date in local format (e.g., `2024-01-16T00:00:00`)   |

---

## Venue Models

### GetVenueDetailsRequest

Used with the `POST /partner/v1/venue/details/byIds` endpoint.

```typescript
GetVenueDetailsRequest {
  ids: List[String],
  location: Option[LatLonPair],
  page: Option[Int],
  pageSize: Option[Int]
}
```

| Field      | Type           | Required | Description                                                |
| ---------- | -------------- | -------- | ---------------------------------------------------------- |
| `ids`      | `List[String]` | Yes      | List of venue IDs to look up                               |
| `location` | `LatLonPair`   | No       | If provided, response includes `kmDistance` for each venue |
| `page`     | `Int`          | No       | Page number for pagination                                 |
| `pageSize` | `Int`          | No       | Items per page (default: 25, max: 100)                     |

### Address

Physical address and coordinates of a venue.

```typescript
Address {
  line: String,
  city: String,
  state: String,
  postal: String,
  lat: Double,
  lon: Double
}
```

| Field    | Type     | Description        |
| -------- | -------- | ------------------ |
| `line`   | `String` | Street address     |
| `city`   | `String` | City name          |
| `state`  | `String` | State abbreviation |
| `postal` | `String` | ZIP / postal code  |
| `lat`    | `Double` | Latitude           |
| `lon`    | `Double` | Longitude          |

### Properties

Venue capability flags.

```typescript
Properties {
  supportsConcessions: Boolean,
  supported: Boolean
}
```

| Field                 | Type      | Description                                               |
| --------------------- | --------- | --------------------------------------------------------- |
| `supportsConcessions` | `Boolean` | Whether the venue supports concession orders through Atom |
| `supported`           | `Boolean` | Whether the venue is fully supported on the Atom platform |

### Venue

Core venue information.

```typescript
Venue {
  id: String,
  name: String,
  address: Address,
  properties: Properties,
  venueUrl: Option[String],
  atomVenueId: Option[String]
}
```

| Field         | Type         | Required | Description                           |
| ------------- | ------------ | -------- | ------------------------------------- |
| `id`          | `String`     | Yes      | Unique venue identifier (starts with C) |
| `name`        | `String`     | Yes      | Venue display name                    |
| `address`     | `Address`    | Yes      | Venue address and coordinates         |
| `properties`  | `Properties` | Yes      | Venue capabilities                    |
| `venueUrl`    | `String`     | No       | URL to the venue page on Atom Tickets |
| `atomVenueId` | `String`     | No       | Internal Atom venue ID                |

### VenueDetail

Venue with optional distance information.

```typescript
VenueDetail {
  venue: Venue,
  kmDistance: Option[Double]
}
```

| Field        | Type     | Required | Description                                      |
| ------------ | -------- | -------- | ------------------------------------------------ |
| `venue`      | `Venue`  | Yes      | The venue data                                   |
| `kmDistance`  | `Double` | No       | Distance in kilometers from the queried location |

### VenueDetailsResponse

Top-level response for venue queries.

```typescript
VenueDetailsResponse {
  venueDetails: List[VenueDetail],
  pageInfo: Option[PageInfo]
}
```

| Field          | Type                | Required | Description                                           |
| -------------- | ------------------- | -------- | ----------------------------------------------------- |
| `venueDetails` | `List[VenueDetail]` | Yes      | List of venue results                                 |
| `pageInfo`     | `PageInfo`          | No       | Pagination metadata (present for paginated endpoints) |

---

## Production Models

### GetProductionDetailsRequest

Used with the `POST /partner/v1/production/details/byIds` endpoint.

```typescript
GetProductionDetailsRequest {
  ids: List[String],
  marketplaceId: Option[String],
  page: Option[Int],
  pageSize: Option[Int]
}
```

| Field           | Type           | Required | Description                            |
| --------------- | -------------- | -------- | -------------------------------------- |
| `ids`           | `List[String]` | Yes      | List of production IDs to look up      |
| `marketplaceId` | `String`       | No       | Marketplace filter (defaults to US)    |
| `page`          | `Int`          | No       | Page number for pagination             |
| `pageSize`      | `Int`          | No       | Items per page (default: 25, max: 100) |

### ProductionIdsResponse

Simple list of production IDs returned by the `byVenue` endpoint.

```typescript
ProductionIdsResponse {
  ids: List[String]
}
```

| Field | Type           | Description              |
| ----- | -------------- | ------------------------ |
| `ids` | `List[String]` | List of production IDs   |

### ImageData

Image assets for a production.

```typescript
ImageData {
  coverImageUrl: String,
  promoImageUrls: List[String]
}
```

| Field            | Type           | Description                           |
| ---------------- | -------------- | ------------------------------------- |
| `coverImageUrl`  | `String`       | URL of the movie poster / cover image |
| `promoImageUrls` | `List[String]` | URLs for promotional images           |

### TrailerData

```typescript
TrailerData {
  trailerUrls: List[String]
}
```

| Field         | Type           | Description            |
| ------------- | -------------- | ---------------------- |
| `trailerUrls` | `List[String]` | URLs to movie trailers |

### ProductionMedia

Combined media assets for a production.

```typescript
ProductionMedia {
  imageData: ImageData,
  trailerData: TrailerData
}
```

| Field         | Type          | Description     |
| ------------- | ------------- | --------------- |
| `imageData`   | `ImageData`   | Image assets    |
| `trailerData` | `TrailerData` | Trailer assets  |

### Cast

```typescript
Cast {
  name: String,
  characterName: Option[String]
}
```

| Field           | Type     | Required | Description      |
| --------------- | -------- | -------- | ---------------- |
| `name`          | `String` | Yes      | Actor name       |
| `characterName` | `String` | No       | Character played |

### Crew

```typescript
Crew {
  name: String,
  role: String
}
```

| Field  | Type     | Required | Description             |
| ------ | -------- | -------- | ----------------------- |
| `name` | `String` | Yes      | Crew member name        |
| `role` | `String` | Yes      | Role (e.g., "Director") |

### Contributors

```typescript
Contributors {
  cast: List[Cast],
  crew: List[Crew]
}
```

| Field  | Type         | Description |
| ------ | ------------ | ----------- |
| `cast` | `List[Cast]` | Cast list   |
| `crew` | `List[Crew]` | Crew list   |

### ProductionDetail

Full production / movie details.

```typescript
ProductionDetail {
  id: String,
  name: String,
  productionMedia: ProductionMedia,
  contributors: Contributors,
  synopsis: Option[String],
  advisoryRating: Option[String],
  genres: Option[List[String]],
  runtimeMinutes: Option[Int],
  releaseDate: Option[String],
  atomUserScore: Option[Double],
  productionUrl: Option[String],
  distributor: Option[String],
  imdbId: Option[String],
  atomProductionId: Option[String]
}
```

| Field              | Type              | Required | Description                                |
| ------------------ | ----------------- | -------- | ------------------------------------------ |
| `id`               | `String`          | Yes      | Unique production identifier (starts with B) |
| `name`             | `String`          | Yes      | Movie title                                |
| `productionMedia`  | `ProductionMedia` | Yes      | Images and trailers                        |
| `contributors`     | `Contributors`    | Yes      | Cast and crew                              |
| `synopsis`         | `String`          | No       | Movie description / plot summary           |
| `advisoryRating`   | `String`          | No       | MPAA rating (e.g., "PG-13", "R", "No Rating") |
| `genres`           | `List[String]`    | No       | Genre list                                 |
| `runtimeMinutes`   | `Int`             | No       | Movie runtime in minutes (0 if unknown)    |
| `releaseDate`      | `String`          | No       | Release date (`YYYY-MM-DD`)                |
| `atomUserScore`    | `Double`          | No       | Atom user score (0-10 scale)               |
| `productionUrl`    | `String`          | No       | URL to the production page on Atom Tickets |
| `distributor`      | `String`          | No       | Film distributor                           |
| `imdbId`           | `String`          | No       | IMDb identifier                            |
| `atomProductionId` | `String`          | No       | Internal Atom production ID                |

### ProductionDetailsResponse

Top-level response for production detail queries.

```typescript
ProductionDetailsResponse {
  productionDetails: List[ProductionDetail],
  pageInfo: Option[PageInfo]
}
```

| Field               | Type                     | Required | Description                |
| ------------------- | ------------------------ | -------- | -------------------------- |
| `productionDetails` | `List[ProductionDetail]` | Yes      | List of production results |
| `pageInfo`          | `PageInfo`               | No       | Pagination metadata        |

---

## Showtime Models

### GetShowtimeDetailsRequest

Used with the `POST /partner/v1/showtime/details/byIds` endpoint.

```typescript
GetShowtimeDetailsRequest {
  ids: List[String],
  page: Option[Int],
  pageSize: Option[Int]
}
```

| Field      | Type           | Required | Description                            |
| ---------- | -------------- | -------- | -------------------------------------- |
| `ids`      | `List[String]` | Yes      | List of showtime IDs to look up        |
| `page`     | `Int`          | No       | Page number                            |
| `pageSize` | `Int`          | No       | Items per page (default: 25, max: 100) |

### GetShowtimesForVenuesRequest

Used with the `POST /partner/v1/showtime/details/forVenues` endpoint.

```typescript
GetShowtimesForVenuesRequest {
  venueIds: Set[String],
  productionIds: Option[Set[String]],
  isoDateBounds: Option[ISODateBounds],
  localDateBounds: Option[LocalDateBounds],
  includeProductionDetails: Option[Boolean],
  marketplaceId: Option[String]
}
```

| Field                      | Type              | Required | Description                                         |
| -------------------------- | ----------------- | -------- | --------------------------------------------------- |
| `venueIds`                 | `Set[String]`     | Yes      | Set of venue IDs to query                           |
| `productionIds`            | `Set[String]`     | No       | Filter to specific productions                      |
| `isoDateBounds`            | `ISODateBounds`   | No*      | Date range (ISO 8601)                               |
| `localDateBounds`          | `LocalDateBounds` | No*      | Date range (local time)                             |
| `includeProductionDetails` | `Boolean`         | No       | If `true`, response includes `productionDetailsMap` |
| `marketplaceId`            | `String`          | No       | Marketplace filter                                  |

*Provide either `isoDateBounds` or `localDateBounds`, not both.

### Attribute

Describes a showtime attribute (e.g., IMAX, Reserved Seating, 3D).

```typescript
Attribute {
  id: String,
  type: String,
  iconUrl: String,
  friendlyName: Option[String],
  description: Option[String]
}
```

| Field          | Type     | Required | Description                                     |
| -------------- | -------- | -------- | ----------------------------------------------- |
| `id`           | `String` | Yes      | Attribute key (e.g., `"RESERVED"`, `"REALD3D"`) |
| `type`         | `String` | Yes      | Attribute type category (e.g., `"SECONDARY"`)   |
| `iconUrl`      | `String` | Yes      | URL to the attribute icon image                 |
| `friendlyName` | `String` | No       | Human-readable name                             |
| `description`  | `String` | No       | Full description of the attribute               |

### Common Showtime Attribute IDs

| ID              | Friendly Name      | Description                                                |
| --------------- | ------------------ | ---------------------------------------------------------- |
| `RESERVED`      | Reserved Seating   | Pick your seats ahead of time                              |
| `STADIUM-SEATING` | Stadium seating  | Stadium-style seating layout                               |
| `CC`            | CC                 | Closed Captioning devices available by request              |
| `DV`            | Descriptive Video  | Audio descriptions for visually impaired                   |
| `DVS`           | Descriptive Video  | Audio descriptions for visually impaired (alternate code)  |
| `REALD3D`       | RealD 3D           | 3D movie presentation                                     |
| `IMAX`          | IMAX               | IMAX large-format presentation                             |

### Price

```typescript
Price {
  value: BigDecimal,
  currencyCode: String
}
```

| Field          | Type         | Description                   |
| -------------- | ------------ | ----------------------------- |
| `value`        | `BigDecimal` | Price amount                  |
| `currencyCode` | `String`     | Currency code (e.g., `"USD"`) |

### Offer

A ticket type and its price.

```typescript
Offer {
  label: String,
  price: Price
}
```

| Field   | Type    | Description                                                        |
| ------- | ------- | ------------------------------------------------------------------ |
| `label` | `String`| Ticket type (e.g., `"Ticket"`, `"Matinee"`, `"Child"`, `"Senior"`) |
| `price` | `Price` | Ticket price                                                       |

### OfferData

```typescript
OfferData {
  offers: List[Offer]
}
```

| Field    | Type          | Description           |
| -------- | ------------- | --------------------- |
| `offers` | `List[Offer]` | Available ticket offers |

### ShowtimeDetail

Full showtime information.

```typescript
ShowtimeDetail {
  showtimeId: String,
  productionId: String,
  venueId: String,
  offerData: OfferData,
  utcShowtimeStart: String,
  localShowtimeStart: String,
  attributes: List[String],
  checkoutUrl: Option[String],
  availableInventory: Option[Int],
  tags: Option[Set[String]]
}
```

| Field                | Type           | Required | Description                                       |
| -------------------- | -------------- | -------- | ------------------------------------------------- |
| `showtimeId`         | `String`       | Yes      | Unique showtime identifier (starts with D)        |
| `productionId`       | `String`       | Yes      | Associated production ID                          |
| `venueId`            | `String`       | Yes      | Associated venue ID                               |
| `offerData`          | `OfferData`    | Yes      | Available ticket offers and pricing               |
| `utcShowtimeStart`   | `String`       | Yes      | Showtime in UTC (ISO 8601, no milliseconds)       |
| `localShowtimeStart` | `String`       | Yes      | Showtime in local timezone (ISO 8601 with offset) |
| `attributes`         | `List[String]` | Yes      | Attribute keys -- look up in `attributeMap`       |
| `checkoutUrl`        | `String`       | No       | Direct link to the Atom checkout flow             |
| `availableInventory` | `Int`          | No       | Number of available seats                         |
| `tags`               | `Set[String]`  | No       | Tags for special event showtimes                  |

### PreOrderDetail

Information about upcoming showtimes available for pre-order.

```typescript
PreOrderDetail {
  productionId: String,
  venueId: String,
  showtimeDays: List[String]
}
```

| Field          | Type           | Required | Description                              |
| -------------- | -------------- | -------- | ---------------------------------------- |
| `productionId` | `String`       | Yes      | Associated production ID                 |
| `venueId`      | `String`       | Yes      | Associated venue ID                      |
| `showtimeDays` | `List[String]` | Yes      | Dates with available pre-order showtimes |

### ShowtimeDetailsResponse

Response for single-venue showtime queries and showtime-by-ID queries.

```typescript
ShowtimeDetailsResponse {
  showtimeDetails: List[ShowtimeDetail],
  preOrderDetails: List[PreOrderDetail],
  attributeMap: Map[String, Attribute]
}
```

| Field             | Type                       | Description                                 |
| ----------------- | -------------------------- | ------------------------------------------- |
| `showtimeDetails` | `List[ShowtimeDetail]`     | List of showtimes                           |
| `preOrderDetails` | `List[PreOrderDetail]`     | Pre-order showtime info                     |
| `attributeMap`    | `Map[String, Attribute]`   | Attribute definitions keyed by attribute ID |

### VenueShowtimeDetails

Showtimes grouped for a single venue (used within the multi-venue response).

```typescript
VenueShowtimeDetails {
  showtimeDetails: List[ShowtimeDetail],
  preOrderDetails: List[PreOrderDetail]
}
```

| Field             | Type                   | Description          |
| ----------------- | ---------------------- | -------------------- |
| `showtimeDetails` | `List[ShowtimeDetail]` | Showtimes at venue   |
| `preOrderDetails` | `List[PreOrderDetail]` | Pre-orders at venue  |

### ShowtimeDetailsForVenuesResponse

Response for multi-venue showtime queries.

```typescript
ShowtimeDetailsForVenuesResponse {
  venueShowtimeDetailsMap: Map[String, VenueShowtimeDetails],
  attributeMap: Map[String, Attribute],
  productionDetailsMap: Map[String, ProductionDetail]
}
```

| Field                     | Type                                | Description                                                        |
| ------------------------- | ----------------------------------- | ------------------------------------------------------------------ |
| `venueShowtimeDetailsMap` | `Map[String, VenueShowtimeDetails]` | Showtimes keyed by venue ID                                        |
| `attributeMap`            | `Map[String, Attribute]`            | Attribute definitions                                              |
| `productionDetailsMap`    | `Map[String, ProductionDetail]`     | Production details (only if `includeProductionDetails` was `true`) |

---

## Endpoint Quick Reference

| # | Method | Route                                                                                          | Description                        |
|---|--------|------------------------------------------------------------------------------------------------|------------------------------------|
| 1 | GET    | `/partner/ping`                                                                                | Health check                       |
| 2 | GET    | `/partner/v1/venue/details/byLocation`                                                         | Search venues by location          |
| 3 | POST   | `/partner/v1/venue/details/byIds`                                                              | Get venues by IDs                  |
| 4 | GET    | `/partner/v1/venue/details/search`                                                             | Search venues by name              |
| 5 | GET    | `/partner/v1/venues/byVendorVenueId/{vendorVenueId}`                                           | Get venue by vendor ID             |
| 6 | GET    | `/partner/v1/production/ids/byVenue/{venueId}`                                                 | Get production IDs at venue        |
| 7 | POST   | `/partner/v1/production/details/byIds`                                                         | Get production details by IDs      |
| 8 | GET    | `/partner/v1/production/search/byName`                                                         | Search productions by name         |
| 9 | GET    | `/partner/v1/productions/byVendorProductionId/{vendorProductionId}`                             | Get production by vendor ID        |
|10 | GET    | `/partner/v1/showtime/details/byVenue/{venueId}`                                               | Get showtimes at venue             |
|11 | POST   | `/partner/v1/showtime/details/byIds`                                                           | Get showtimes by IDs               |
|12 | POST   | `/partner/v1/showtime/details/forVenues`                                                       | Get showtimes for multiple venues  |
|13 | GET    | `/partner/v1/venues/{venueId}/showtimes/byVendorShowtimeId/{vendorShowtimeId}`                  | Get showtime by vendor showtime ID |
|14 | GET    | `/partner/v1/venues/byVendorVenueId/{vendorVenueId}/showtimes/byVendorShowtimeId/{vendorShowtimeId}` | Get showtime by vendor venue+showtime IDs |
|15 | POST   | `/ordering/v2/aggregation/checkout/refresh`                                                         | Refresh checkout with pricing and offers  |
|16 | GET    | `/ordering/v1/discovery/auditoriums`                                                                | Discover auditorium layout and seats      |
|17 | POST   | `/ordering/v1/customer/account/guest`                                                               | Create guest customer account             |
|18 | POST   | `/ordering/v1/customer/account/authenticate`                                                        | Authenticate existing customer            |
|19 | POST   | `/ordering/v1/inventory/lease`                                                                      | Lease (hold) seats for a showtime         |
|20 | POST   | `/ordering/v2/customer/orders/preview`                                                              | Preview order with cost breakdown         |
|21 | POST   | `/ordering/v1/customer/orders`                                                                      | Place a ticket order with payment         |
|22 | GET    | `/ordering/v1/customer/orders/{id}/status`                                                          | Get current order status                  |
|23 | GET    | `/ordering/v2/customer/orders/{id}/summary`                                                         | Get detailed order summary                |
|24 | DELETE | `/v1/customer/orders/{id}`                                                                          | Cancel an existing order                  |

---

# ORDERING API

The Ordering API enables the full ticket purchasing flow: checkout refresh, auditorium discovery, customer account management, seat leasing, order preview, order placement, status tracking, and cancellation.

All Ordering API requests require the `x-api-key` header with your `{AtomPartnerApiKey}` value.

## Ordering Error Codes

| Error Code                    | Description                                                    |
| ----------------------------- | -------------------------------------------------------------- |
| `PRODUCT_NOT_FOUND`           | The specified production or product does not exist              |
| `OFFER_NOT_FOUND`             | The specified offer ID is invalid or no longer available        |
| `INVENTORY_UNAVAILABLE`       | No inventory available for the requested showtime              |
| `SEAT_UNAVAILABLE`            | One or more requested seats are not available                  |
| `DUPLICATE_CLIENT_REQUEST_ID` | A request with this clientRequestId has already been processed |
| `INVALID_SHOWTIME`            | The specified showtime is invalid or has passed                |
| `FRAUD_DETECTED`              | The transaction was flagged for suspected fraud                |
| `INVALID_CREDIT_CARD_NUMBER`  | The provided credit card number is invalid                     |
| `PROCESSOR_DECLINED`          | The payment processor declined the transaction                 |
| `GENERIC_ERROR`               | An unexpected error occurred                                   |
| `ORDER_NOT_FOUND`             | The specified order does not exist                             |
| `ORDER_NOT_CANCELLABLE`       | The order is not in a state that allows cancellation           |
| `CANCELLATION_WINDOW_EXPIRED` | The cancellation window for this order has expired             |
| `REFUND_PROCESSING_ERROR`     | An error occurred while processing the refund                  |

---

## 15. POST /ordering/v2/aggregation/checkout/refresh

Refresh checkout with aggregated pricing, fees, and available offers for a showtime.

### Request Body -- `CheckoutRefreshRequest`

| Field        | Type                   | Required | Description                                  |
| ------------ | ---------------------- | -------- | -------------------------------------------- |
| `showtimeId` | `String`               | Yes      | The showtime identifier                      |
| `tickets`    | `List[TicketSelection]`| Yes      | Selected tickets with offer IDs and quantities |

### Request

```bash
curl -X POST \
  'https://api-beta.atomtickets.com/ordering/v2/aggregation/checkout/refresh' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "showtimeId": "D00747321039",
    "tickets": [
      { "offerId": "adult-standard", "quantity": 2 }
    ]
  }'
```

### Response

Returns `CheckoutRefreshResponse` with pricing breakdown and available offers.

### Error Codes

`PRODUCT_NOT_FOUND`, `OFFER_NOT_FOUND`, `INVALID_SHOWTIME`, `GENERIC_ERROR`

---

## 16. GET /ordering/v1/discovery/auditoriums

Discover auditorium layout and available seats for a showtime.

### Parameters

| Parameter    | Type     | Required | Description                                    |
| ------------ | -------- | -------- | ---------------------------------------------- |
| `showtimeId` | `String` | Yes      | The showtime identifier to get auditorium info |

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/ordering/v1/discovery/auditoriums?showtimeId=D00747321039' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `AuditoriumDiscoveryResponse` with seat map and availability. Each seat includes `seatId`, `row`, `number`, `status` (AVAILABLE, OCCUPIED, HELD, BROKEN), and `seatType`.

### Error Codes

`INVALID_SHOWTIME`, `GENERIC_ERROR`

---

## 17. POST /ordering/v1/customer/account/guest

Create a guest customer account for checkout without requiring full registration.

### Request Body -- `GuestAccountRequest`

| Field       | Type     | Required | Description         |
| ----------- | -------- | -------- | ------------------- |
| `email`     | `String` | Yes      | Guest email address |
| `firstName` | `String` | Yes      | Guest first name    |
| `lastName`  | `String` | Yes      | Guest last name     |

### Request

```bash
curl -X POST \
  'https://api-beta.atomtickets.com/ordering/v1/customer/account/guest' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "email": "guest@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }'
```

### Response

Returns `CustomerAccountResponse` with `customerId`, `email`, `firstName`, `lastName`, and `sessionToken`.

### Error Codes

`GENERIC_ERROR`

---

## 18. POST /ordering/v1/customer/account/authenticate

Authenticate an existing customer account to retrieve their session for ordering.

### Request Body -- `AuthenticateCustomerRequest`

| Field      | Type     | Required | Description            |
| ---------- | -------- | -------- | ---------------------- |
| `email`    | `String` | Yes      | Customer email address |
| `password` | `String` | Yes      | Customer password      |

### Request

```bash
curl -X POST \
  'https://api-beta.atomtickets.com/ordering/v1/customer/account/authenticate' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "email": "user@example.com",
    "password": "securepassword"
  }'
```

### Response

Returns `CustomerAccountResponse` with `customerId`, `email`, `firstName`, `lastName`, and `sessionToken`.

### Error Codes

`GENERIC_ERROR`

---

## 19. POST /ordering/v1/inventory/lease

Lease (temporarily hold) specific seats for a showtime. The lease expires after a set duration, after which the seats become available again.

### Request Body -- `InventoryLeaseRequest`

| Field        | Type           | Required | Description                  |
| ------------ | -------------- | -------- | ---------------------------- |
| `showtimeId` | `String`       | Yes      | The showtime identifier      |
| `seatIds`    | `List[String]` | Yes      | List of seat IDs to lease    |

### Request

```bash
curl -X POST \
  'https://api-beta.atomtickets.com/ordering/v1/inventory/lease' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "showtimeId": "D00747321039",
    "seatIds": ["A1", "A2"]
  }'
```

### Response

Returns `InventoryLeaseResponse` with `leaseId`, `showtimeId`, `seatIds`, and `expiresAt` (ISO 8601 timestamp).

### Error Codes

`INVENTORY_UNAVAILABLE`, `SEAT_UNAVAILABLE`, `INVALID_SHOWTIME`, `GENERIC_ERROR`

---

## 20. POST /ordering/v2/customer/orders/preview

Preview an order with a full cost breakdown before placing it. Requires a valid lease.

### Request Body -- `OrderPreviewRequest`

| Field        | Type                    | Required | Description                    |
| ------------ | ----------------------- | -------- | ------------------------------ |
| `showtimeId` | `String`                | Yes      | The showtime identifier        |
| `tickets`    | `List[TicketSelection]` | Yes      | Selected tickets               |
| `leaseId`    | `String`                | Yes      | The inventory lease identifier |

### Request

```bash
curl -X POST \
  'https://api-beta.atomtickets.com/ordering/v2/customer/orders/preview' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "showtimeId": "D00747321039",
    "tickets": [
      { "offerId": "adult-standard", "quantity": 2 }
    ],
    "leaseId": "lease-abc-123"
  }'
```

### Response

Returns `OrderPreviewResponse` with `previewId`, `showtimeId`, `tickets`, `pricing` (subtotal, fees, tax, total), and `leaseId`.

### Error Codes

`OFFER_NOT_FOUND`, `INVENTORY_UNAVAILABLE`, `INVALID_SHOWTIME`, `GENERIC_ERROR`

---

## 21. POST /ordering/v1/customer/orders

Place a ticket order with payment. Requires a valid preview and customer account.

### Request Body -- `PlaceOrderRequest`

| Field             | Type          | Required | Description                                      |
| ----------------- | ------------- | -------- | ------------------------------------------------ |
| `previewId`       | `String`      | Yes      | The order preview identifier                     |
| `customerId`      | `String`      | Yes      | The customer identifier                          |
| `payment`         | `PaymentInfo` | Yes      | Payment details                                  |
| `clientRequestId` | `String`      | No       | Idempotency key to prevent duplicate orders      |

### PaymentInfo

| Field             | Type      | Description              |
| ----------------- | --------- | ------------------------ |
| `cardNumber`      | `String`  | Credit card number       |
| `expirationMonth` | `Int`     | Card expiration month    |
| `expirationYear`  | `Int`     | Card expiration year     |
| `cvv`             | `String`  | Card security code       |
| `billingZip`      | `String`  | Billing ZIP code         |

### Request

```bash
curl -X POST \
  'https://api-beta.atomtickets.com/ordering/v1/customer/orders' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {AtomPartnerApiKey}' \
  -d '{
    "previewId": "preview-xyz-789",
    "customerId": "cust-abc-123",
    "payment": {
      "cardNumber": "4111111111111111",
      "expirationMonth": 12,
      "expirationYear": 2027,
      "cvv": "123",
      "billingZip": "90210"
    },
    "clientRequestId": "unique-request-id-001"
  }'
```

### Response

Returns `PlaceOrderResponse` with `orderId`, `status`, and `confirmationCode`.

### Error Codes

`DUPLICATE_CLIENT_REQUEST_ID`, `FRAUD_DETECTED`, `INVALID_CREDIT_CARD_NUMBER`, `PROCESSOR_DECLINED`, `INVENTORY_UNAVAILABLE`, `GENERIC_ERROR`

---

## 22. GET /ordering/v1/customer/orders/{id}/status

Get the current status of an order.

### Path Parameters

| Parameter | Type     | Required | Description          |
| --------- | -------- | -------- | -------------------- |
| `id`      | `String` | Yes      | The order identifier |

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/ordering/v1/customer/orders/order-abc-123/status' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `OrderStatusResponse` with `orderId` and `status` (e.g., PENDING, CONFIRMED, CANCELLED, REFUNDED).

### Error Codes

`ORDER_NOT_FOUND`, `GENERIC_ERROR`

---

## 23. GET /ordering/v2/customer/orders/{id}/summary

Get a detailed summary of a completed order including tickets, seats, and pricing.

### Path Parameters

| Parameter | Type     | Required | Description          |
| --------- | -------- | -------- | -------------------- |
| `id`      | `String` | Yes      | The order identifier |

### Request

```bash
curl -X GET \
  'https://api-beta.atomtickets.com/ordering/v2/customer/orders/order-abc-123/summary' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `OrderSummaryResponse` with `orderId`, `status`, `confirmationCode`, `showtimeId`, `venueId`, `productionId`, `tickets`, `seats`, and `pricing` (subtotal, fees, tax, total).

### Error Codes

`ORDER_NOT_FOUND`, `GENERIC_ERROR`

---

## 24. DELETE /v1/customer/orders/{id}

Cancel an existing order. Subject to cancellation window policies.

### Path Parameters

| Parameter | Type     | Required | Description          |
| --------- | -------- | -------- | -------------------- |
| `id`      | `String` | Yes      | The order identifier |

### Request

```bash
curl -X DELETE \
  'https://api-beta.atomtickets.com/v1/customer/orders/order-abc-123' \
  -H 'x-api-key: {AtomPartnerApiKey}'
```

### Response

Returns `CancelOrderResponse` with `orderId`, `status`, and `refundAmount`.

### Error Codes

`ORDER_NOT_FOUND`, `ORDER_NOT_CANCELLABLE`, `CANCELLATION_WINDOW_EXPIRED`, `REFUND_PROCESSING_ERROR`, `GENERIC_ERROR`

---

# ORDERING DATA MODELS

---

## TicketSelection

```typescript
TicketSelection {
  offerId: String,
  quantity: Int
}
```

| Field      | Type     | Description                            |
| ---------- | -------- | -------------------------------------- |
| `offerId`  | `String` | The offer identifier                   |
| `quantity` | `Int`    | Number of tickets for this offer type  |

## PricingBreakdown

```typescript
PricingBreakdown {
  subtotal: Price,
  fees: Price,
  tax: Price,
  total: Price
}
```

| Field      | Type    | Description             |
| ---------- | ------- | ----------------------- |
| `subtotal` | `Price` | Ticket subtotal         |
| `fees`     | `Price` | Service and booking fees|
| `tax`      | `Price` | Applicable taxes        |
| `total`    | `Price` | Total amount to charge  |

## CheckoutOffer

```typescript
CheckoutOffer {
  offerId: String,
  label: String,
  price: Price
}
```

| Field     | Type     | Description                              |
| --------- | -------- | ---------------------------------------- |
| `offerId` | `String` | Unique offer identifier                  |
| `label`   | `String` | Offer label (e.g., Adult, Child, Senior) |
| `price`   | `Price`  | Offer price                              |

## CheckoutRefreshResponse

```typescript
CheckoutRefreshResponse {
  showtimeId: String,
  tickets: List[TicketSelection],
  pricing: PricingBreakdown,
  offers: List[CheckoutOffer]
}
```

## Seat

```typescript
Seat {
  seatId: String,
  row: String,
  number: String,
  status: String,
  seatType: String
}
```

| Field      | Type     | Description                                             |
| ---------- | -------- | ------------------------------------------------------- |
| `seatId`   | `String` | Unique seat identifier                                  |
| `row`      | `String` | Seat row label                                          |
| `number`   | `String` | Seat number                                             |
| `status`   | `String` | Current status: AVAILABLE, OCCUPIED, HELD, or BROKEN    |
| `seatType` | `String` | Type of seat (e.g., Standard, Premium, Wheelchair)      |

## AuditoriumDiscoveryResponse

```typescript
AuditoriumDiscoveryResponse {
  auditoriumId: String,
  showtimeId: String,
  seatMapAvailable: Boolean,
  seats: List[Seat]
}
```

## CustomerAccountResponse

```typescript
CustomerAccountResponse {
  customerId: String,
  email: String,
  firstName: String,
  lastName: String,
  sessionToken: String
}
```

## InventoryLeaseResponse

```typescript
InventoryLeaseResponse {
  leaseId: String,
  showtimeId: String,
  seatIds: List[String],
  expiresAt: String
}
```

## OrderPreviewResponse

```typescript
OrderPreviewResponse {
  previewId: String,
  showtimeId: String,
  tickets: List[TicketSelection],
  pricing: PricingBreakdown,
  leaseId: String
}
```

## PaymentInfo

```typescript
PaymentInfo {
  cardNumber: String,
  expirationMonth: Int,
  expirationYear: Int,
  cvv: String,
  billingZip: String
}
```

## PlaceOrderResponse

```typescript
PlaceOrderResponse {
  orderId: String,
  status: String,
  confirmationCode: String
}
```

## OrderStatusResponse

```typescript
OrderStatusResponse {
  orderId: String,
  status: String
}
```

## OrderSummaryResponse

```typescript
OrderSummaryResponse {
  orderId: String,
  status: String,
  confirmationCode: String,
  showtimeId: String,
  venueId: String,
  productionId: String,
  tickets: List[TicketSelection],
  seats: List[Seat],
  pricing: PricingBreakdown
}
```

## CancelOrderResponse

```typescript
CancelOrderResponse {
  orderId: String,
  status: String,
  refundAmount: Price
}
```

---

## Ordering Best Practices

- **Use idempotency keys**: Always provide a `clientRequestId` when placing orders to prevent duplicate charges if a request is retried.
- **Respect lease expiration**: Seat leases have a limited duration. Complete the order before the lease expires, or the seats will be released.
- **Preview before placing**: Always call the preview endpoint before placing an order to confirm the final pricing with the customer.
- **Handle error codes**: Implement specific handling for each error code rather than treating all errors the same. Payment errors (FRAUD_DETECTED, PROCESSOR_DECLINED, INVALID_CREDIT_CARD_NUMBER) may require different user flows than inventory errors (SEAT_UNAVAILABLE, INVENTORY_UNAVAILABLE).
- **Poll order status**: After placing an order, poll the status endpoint to confirm the order reaches CONFIRMED status.
- **Cancellation windows**: Orders can only be cancelled within the cancellation window. Check for ORDER_NOT_CANCELLABLE and CANCELLATION_WINDOW_EXPIRED errors.
- **Rate limits apply**: All ordering endpoints are subject to the same rate limits (429 Too Many Requests). Implement exponential backoff.