openapi: 3.0.3
info:
  title: AMC Theatres Barcodes Showtimes API
  description: 'The AMC Theatres API is a public REST API published by AMC Entertainment Holdings

    that exposes data and transactional capabilities for AMC theatres, movies, showtimes,

    locations, loyalty, concessions, orders, refunds, media, and webhooks. It is intended

    for partner integrations such as movie discovery, ticket sales, dine-in / express pickup

    concession ordering, AMC Stubs loyalty integrations, and entertainment listings on

    third-party sites and apps.


    Authentication is performed by sending a vendor API key in the `X-AMC-Vendor-Key`

    request header. Responses follow a HAL-style envelope (`pageSize`, `pageNumber`,

    `count`, `_embedded`, `_links`) for collections.


    This OpenAPI definition was reconstructed from the public AMC Developer Portal

    documentation (developers.amctheatres.com) and known integrations. The dev portal

    blocks automated retrieval, so this spec was assembled from third-party mirrors

    of the AMC documentation and verified against open-source AMC API clients.'
  version: v2
  contact:
    name: AMC Theatres Developer Portal
    url: https://developers.amctheatres.com
  termsOfService: https://www.amctheatres.com/legal/terms-of-use
  license:
    name: AMC Theatres API Terms of Use
    url: https://www.amctheatres.com/legal/terms-of-use
servers:
- url: https://api.amctheatres.com
  description: AMC Theatres production API
security:
- VendorKey: []
tags:
- name: Showtimes
  description: Theatre showtimes for movies, including embargoed and proximity-based searches.
paths:
  /v2/theatres/{theatre-number}/showtimes:
    get:
      summary: List Showtimes for a Theatre
      description: Returns all future showtimes for the specified theatre.
      operationId: listTheatreShowtimes
      tags:
      - Showtimes
      parameters:
      - $ref: '#/components/parameters/TheatreNumber'
      - name: movie-id
        in: query
        schema:
          type: integer
        description: Filter to showtimes for a specific movie id.
      - $ref: '#/components/parameters/IncludeAttributes'
      - $ref: '#/components/parameters/ExcludeAttributes'
      - $ref: '#/components/parameters/AttributeOperator'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Showtimes collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowtimeCollection'
  /v2/theatres/{theatre-number}/showtimes/{date}:
    get:
      summary: List Showtimes for a Theatre on a Date
      description: Returns all showtimes for the specified theatre on the specified date that meet the supplied search criteria.
      operationId: listTheatreShowtimesByDate
      tags:
      - Showtimes
      parameters:
      - $ref: '#/components/parameters/TheatreNumber'
      - name: date
        in: path
        required: true
        schema:
          type: string
          format: date
        description: Date in ISO-8601 (YYYY-MM-DD) format.
      - $ref: '#/components/parameters/IncludeAttributes'
      - $ref: '#/components/parameters/ExcludeAttributes'
      - $ref: '#/components/parameters/AttributeOperator'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Showtimes collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowtimeCollection'
  /v2/theatres/{theatre-number}/showtimes/{date}/views/embargoed:
    get:
      summary: List Embargoed Showtimes for a Theatre on a Date
      description: Returns all embargoed showtimes for the specified theatre and date.
      operationId: listEmbargoedShowtimes
      tags:
      - Showtimes
      parameters:
      - $ref: '#/components/parameters/TheatreNumber'
      - name: date
        in: path
        required: true
        schema:
          type: string
          format: date
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Embargoed showtimes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowtimeCollection'
  /v2/theatres/{theatre-number}/movies/{movie-id}/earliest-showtime:
    get:
      summary: Get Earliest Showtime For Movie at Theatre
      description: Returns the earliest showtime for a specific movie id at the specified theatre.
      operationId: getEarliestShowtime
      tags:
      - Showtimes
      parameters:
      - $ref: '#/components/parameters/TheatreNumber'
      - name: movie-id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Showtime representation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Showtime'
  /v2/showtimes/{id}:
    get:
      summary: Get Showtime By Id
      description: Returns the showtime with the specified id.
      operationId: getShowtime
      tags:
      - Showtimes
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Showtime representation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Showtime'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/showtimes/views/current-location/{date}/{latitude}/{longitude}:
    get:
      summary: List Showtimes Near a Location
      description: Returns all showtimes in proximity to the supplied latitude and longitude on the specified date.
      operationId: listShowtimesByLocation
      tags:
      - Showtimes
      parameters:
      - name: date
        in: path
        required: true
        schema:
          type: string
          format: date
      - name: latitude
        in: path
        required: true
        schema:
          type: number
          format: double
      - name: longitude
        in: path
        required: true
        schema:
          type: number
          format: double
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Showtimes near the location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowtimeCollection'
components:
  schemas:
    Showtime:
      type: object
      properties:
        id:
          type: integer
        movieId:
          type: integer
        movieName:
          type: string
        showDateTimeUtc:
          type: string
          format: date-time
        showDateTimeLocal:
          type: string
          format: date-time
        utcOffset:
          type: string
        theatreId:
          type: integer
        auditorium:
          type: integer
        layoutId:
          type: integer
        wamc:
          type: string
        sortableMovieName:
          type: string
        movieSlug:
          type: string
        runTime:
          type: integer
        mpaaRating:
          type: string
        genre:
          type: string
        purchaseUrl:
          type: string
          format: uri
        mobilePurchaseUrl:
          type: string
          format: uri
        ticketPrices:
          type: array
          items:
            $ref: '#/components/schemas/TicketPrice'
        utcSession:
          type: string
        isAlmostSoldOut:
          type: boolean
        isSoldOut:
          type: boolean
        isCanceled:
          type: boolean
        isPrivateRental:
          type: boolean
        isDiscountMatineePriced:
          type: boolean
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
        media:
          type: object
        _links:
          $ref: '#/components/schemas/HalLinks'
    ShowtimeCollection:
      allOf:
      - $ref: '#/components/schemas/PagedCollection'
      - type: object
        properties:
          _embedded:
            type: object
            properties:
              showtimes:
                type: array
                items:
                  $ref: '#/components/schemas/Showtime'
    ApiError:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        errorCode:
          type: string
        moreInfo:
          type: string
    TicketPrice:
      type: object
      properties:
        priceType:
          type: string
        sku:
          type: string
        price:
          type: number
          format: double
        tax:
          type: number
          format: double
        formattedPrice:
          type: string
        formattedTax:
          type: string
    HalLinks:
      type: object
      additionalProperties:
        type: object
        properties:
          href:
            type: string
          templated:
            type: boolean
    Attribute:
      type: object
      properties:
        id:
          type: integer
        code:
          type: string
        name:
          type: string
        shortDescription:
          type: string
        longDescription:
          type: string
        url:
          type: string
          format: uri
        sort:
          type: integer
        appliesToMovie:
          type: boolean
        appliesToShowtime:
          type: boolean
        appliesToTheatre:
          type: boolean
        media:
          type: object
        _links:
          $ref: '#/components/schemas/HalLinks'
    PagedCollection:
      type: object
      properties:
        pageSize:
          type: integer
        pageNumber:
          type: integer
        count:
          type: integer
        _links:
          $ref: '#/components/schemas/HalLinks'
  parameters:
    PageSize:
      name: page-size
      in: query
      description: Results per page (max 100). Defaults to 10.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    ExcludeAttributes:
      name: exclude-attributes
      in: query
      description: Comma-delimited list of attributes that results must not have.
      schema:
        type: string
    TheatreNumber:
      name: theatre-number
      in: path
      required: true
      description: The theatre number / id.
      schema:
        type: integer
    PageNumber:
      name: page-number
      in: query
      description: Page number to retrieve. Defaults to 1.
      schema:
        type: integer
        minimum: 1
        default: 1
    IncludeAttributes:
      name: include-attributes
      in: query
      description: Comma-delimited list of attributes that results must have.
      schema:
        type: string
    AttributeOperator:
      name: attribute-operator
      in: query
      description: Whether the include/exclude attribute filter is `and` (all) or `or` (any).
      schema:
        type: string
        enum:
        - and
        - or
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    VendorKey:
      type: apiKey
      in: header
      name: X-AMC-Vendor-Key
      description: AMC vendor API key issued via the AMC Theatres developer portal.
externalDocs:
  description: AMC Theatres Developer Portal
  url: https://developers.amctheatres.com