openapi: 3.2.0
info:
  title: Reference Tiers API
  version: 1.0.0
servers:
- url: https://api.beehiiv.com/v2
  description: Default
tags:
- name: Tiers
paths:
  /publications/{publicationId}/tiers:
    post:
      operationId: create
      summary: 'Create a tier <Badge intent="info" minimal outlined>OAuth Scope: tiers:write</Badge>'
      description: Create a new tier for a publication.
      tags:
      - Tiers
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_tiers_TierResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                prices_attributes:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_tiers_TierPricesAttributesItem'
              required:
              - name
    get:
      operationId: index
      summary: 'List tiers <Badge intent="info" minimal outlined>OAuth Scope: tiers:read</Badge>'
      description: Retrieve all tiers belonging to a specific publication
      tags:
      - Tiers
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: expand[]
        in: query
        description: Optional list of expandable objects.<br>`stats` - Returns statistics about the tier(s).<br>`prices` - Returns prices for the tier(s).
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.
        required: false
        schema:
          type: integer
      - name: page
        in: query
        description: 'Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.'
        required: false
        schema:
          type: integer
      - name: direction
        in: query
        description: The direction that the results are sorted in. Defaults to asc<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest.
        required: false
        schema:
          $ref: '#/components/schemas/type__RequestDirection'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_tiers_IndexTiersResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
  /publications/{publicationId}/tiers/{tierId}:
    get:
      operationId: show
      summary: 'Get tier <Badge intent="info" minimal outlined>OAuth Scope: tiers:read</Badge>'
      description: Retrieve a single tier belonging to a specific publication
      tags:
      - Tiers
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: tierId
        in: path
        description: The prefixed ID of the tier object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_TierId'
      - name: expand[]
        in: query
        description: Optional list of expandable objects.<br>`stats` - Returns statistics about the tier(s).<br>`prices` - Returns prices for the tier(s).
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_tiers_TierResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
    put:
      operationId: put
      summary: 'Update a tier <Badge intent="info" minimal outlined>OAuth Scope: tiers:write</Badge>'
      description: Update an existing tier belonging to a specific publication
      tags:
      - Tiers
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: tierId
        in: path
        description: The prefixed ID of the tier object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_TierId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_tiers_TierResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                prices_attributes:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_tiers_UpdateTierPriceRequest'
    patch:
      operationId: patch
      summary: 'Update a tier <Badge intent="info" minimal outlined>OAuth Scope: tiers:write</Badge>'
      description: Update an existing tier belonging to a specific publication
      tags:
      - Tiers
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: tierId
        in: path
        description: The prefixed ID of the tier object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_TierId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_tiers_TierResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                prices_attributes:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_tiers_UpdateTierPriceRequest'
components:
  schemas:
    type_tiers_TierPriceCurrency:
      type: string
      enum:
      - usd
      - aud
      - cad
      - eur
      - gbp
      - inr
      - brl
      - mxn
      - nzd
      - dkk
      title: TierPriceCurrency
    type_tiers_TierStatus:
      type: string
      enum:
      - active
      - archived
      description: Returns whether or not the tier has any active prices.
      title: TierStatus
    type_tiers_IndexTiersResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/type_tiers_Tier'
        limit:
          type: integer
          description: The limit placed on the results. If no limit was specified in the request,this defaults to 10.
        page:
          type: integer
          default: 1
          description: The page number the results are from. If no page was specified in the request, this defaults to page 1.
        total_results:
          type: integer
          description: The total number of results from all pages.
        total_pages:
          type: integer
          description: The total number of pages.
      required:
      - data
      - limit
      - page
      - total_results
      - total_pages
      title: IndexTiersResponse
    type_tiers_TierResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_tiers_Tier'
      title: TierResponse
    type_ids_PublicationId:
      type: string
      description: The prefixed ID of the publication.
      title: PublicationId
    type_ids_PriceId:
      type: string
      description: The prefixed ID of the price.
      title: PriceId
    type_tiers_UpdateTierPriceRequest:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/type_ids_PriceId'
          description: ID of the existing price.
        currency:
          $ref: '#/components/schemas/type_tiers_TierPriceCurrency'
        amount_cents:
          type: integer
        interval:
          $ref: '#/components/schemas/type_tiers_TierPriceInterval'
        interval_display:
          type: string
        cta:
          type: string
        features:
          type: array
          items:
            type: string
        delete:
          type: boolean
          default: false
          description: Optionally delete the price when updating the tier.
      required:
      - id
      - currency
      - amount_cents
      - interval
      title: UpdateTierPriceRequest
    type__RequestDirection:
      type: string
      enum:
      - asc
      - desc
      default: asc
      description: The direction of the request. Defaults to `asc`.
      title: RequestDirection
    type__Error:
      type: object
      properties:
        status:
          type: integer
        statusText:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/type__ErrorDetail'
      required:
      - status
      - statusText
      - errors
      description: The top level error response.
      title: Error
    type__ErrorDetail:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
      title: ErrorDetail
    type_tiers_TierStats:
      type: object
      properties:
        active_subscriptions:
          type: integer
          description: Total number of active subscriptions belonging to this tier.
      required:
      - active_subscriptions
      description: 'Optional list of stats for a tier. Retrievable by including `expand: [stats]` in the tier request body.'
      title: TierStats
    type_tiers_TierPriceInterval:
      type: string
      enum:
      - month
      - quarter
      - year
      - one_time
      - donation
      title: TierPriceInterval
    type_tiers_TierPrice:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/type_ids_PriceId'
        currency:
          $ref: '#/components/schemas/type_tiers_TierPriceCurrency'
        amount_cents:
          type: integer
        enabled:
          type: boolean
          default: true
        interval:
          $ref: '#/components/schemas/type_tiers_TierPriceInterval'
        denominator:
          type: string
        cta:
          type: string
          description: When using the external Stripe checkout, this text will be displayed on the button
        features:
          type: array
          items:
            type: string
      description: Price belonging to a Tier
      title: TierPrice
    type_tiers_TierPricesAttributesItem:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/type_tiers_TierPriceCurrency'
        amount_cents:
          type: integer
        enabled:
          type: boolean
          default: true
        interval:
          $ref: '#/components/schemas/type_tiers_TierPriceInterval'
        interval_display:
          type: string
        cta:
          type: string
        features:
          type: array
          items:
            type: string
      required:
      - currency
      - amount_cents
      - interval
      title: TierPricesAttributesItem
    type_tiers_Tier:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/type_ids_TierId'
        name:
          type: string
        status:
          $ref: '#/components/schemas/type_tiers_TierStatus'
          description: Returns whether or not the tier has any active prices.
        description:
          type: string
          default: Super engaged readers
        stats:
          $ref: '#/components/schemas/type_tiers_TierStats'
        prices:
          type: array
          items:
            $ref: '#/components/schemas/type_tiers_TierPrice'
          description: 'Optional list of prices for a tier. Retrievable by including `expand: [prices]` in the tier request body.'
      required:
      - id
      - name
      - status
      description: The subscription tier object.
      title: Tier
    type_ids_TierId:
      type: string
      description: The prefixed ID of the tier.
      title: TierId
  securitySchemes:
    BearerAuthScheme:
      type: http
      scheme: bearer