beehiiv

beehiiv Tiers API

The Tiers API from beehiiv — 2 operation(s) for tiers.

Documentation GitHub OpenAPI

Operations 5

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /publications/{publicationId}/tiers Create a subscription tier · Create a tier OAuth Scope: tiers:write #

Ask an LLM

“How do I add a new paid tier to my newsletter?”

“Can I set prices when creating a tier?”

Tell an agent

Create a tier named {name} on publication {publication}.

Create tier {name} with prices {prices_attributes}.

GET /publications/{publicationId}/tiers List a publication's subscription tiers · List tiers OAuth Scope: tiers:read #

Ask an LLM

“What paid tiers does my newsletter offer?”

“Can I see my tiers along with their prices?”

Tell an agent

List subscription tiers on publication {publication}.

Show the paid tiers on {publication} with {expand} expanded.

GET /publications/{publicationId}/tiers/{tierId} Get one subscription tier · Get tier OAuth Scope: tiers:read #

Ask an LLM

“What's included in a specific tier and what does it cost?”

“Can I retrieve a single tier by its ID?”

Tell an agent

Get tier {tier} on publication {publication}.

Show what tier {tier} includes and costs.

PUT /publications/{publicationId}/tiers/{tierId} Update a subscription tier (PUT) · Update a tier OAuth Scope: tiers:write #

Ask an LLM

“How do I PUT a new name or description onto an existing tier?”

“Can I replace a tier's prices with a PUT request?”

Tell an agent

PUT name {name} on tier {tier} in publication {publication}.

Replace the prices of tier {tier} with {prices_attributes} via PUT.

PATCH /publications/{publicationId}/tiers/{tierId} Update a subscription tier (PATCH) · Update a tier OAuth Scope: tiers:write #

Ask an LLM

“Can I PATCH just the description of an existing tier?”

“What's the PATCH call for changing a tier's prices?”

Tell an agent

PATCH tier {tier} on {publication} with description {description}.

PATCH the prices on tier {tier} to {prices_attributes}.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/beehiiv:beehiiv-tiers-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

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 OAuth Scope: tiers:write'
      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 OAuth Scope: tiers:read'
      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 OAuth Scope: tiers:read'
      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 OAuth Scope: tiers:write'
      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 OAuth Scope: tiers:write'
      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_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_TierPriceInterval:
      type: string
      enum:
      - month
      - quarter
      - year
      - one_time
      - donation
      title: TierPriceInterval
    type_ids_TierId:
      type: string
      description: The prefixed ID of the tier.
      title: TierId
    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_ids_PublicationId:
      type: string
      description: The prefixed ID of the publication.
      title: PublicationId
    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_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_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_TierStatus:
      type: string
      enum:
      - active
      - archived
      description: Returns whether or not the tier has any active prices.
      title: TierStatus
    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__RequestDirection:
      type: string
      enum:
      - asc
      - desc
      default: asc
      description: The direction of the request. Defaults to `asc`.
      title: RequestDirection
    type_ids_PriceId:
      type: string
      description: The prefixed ID of the price.
      title: PriceId
    type__ErrorDetail:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
      title: ErrorDetail
    type_tiers_TierPriceCurrency:
      type: string
      enum:
      - usd
      - aud
      - cad
      - eur
      - gbp
      - inr
      - brl
      - mxn
      - nzd
      - dkk
      title: TierPriceCurrency
    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
  securitySchemes:
    BearerAuthScheme:
      type: http
      scheme: bearer

beehiiv Tiers API

Operations 5

Documentation

Specifications

Schemas & Data

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification