Ghost Tiers API

openapi: 3.2.0
info:
  title: Ghost Org Tiers API
  version: '5.0'
  termsOfService: https://ghost.org/terms/
  description: 'Operations tagged Tiers across 2 of this provider''s published API definitions: ghost-org-admin-api-openapi.yml, ghost-org-content-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{site}.ghost.io/ghost/api/admin
  description: Ghost Pro Hosted Site
  variables:
    site:
      default: your-site
      description: Your Ghost site subdomain
- url: '{protocol}://{domain}/ghost/api/admin'
  description: Self-Hosted Ghost Instance
  variables:
    protocol:
      default: https
      enum:
      - https
      - http
    domain:
      default: localhost:2368
      description: Your Ghost instance domain and port
- url: https://{site}.ghost.io/ghost/api/content
  description: Ghost Pro Hosted Site
  variables:
    site:
      default: your-site
      description: Your Ghost site subdomain
- url: '{protocol}://{domain}/ghost/api/content'
  description: Self-Hosted Ghost Instance
  variables:
    protocol:
      default: https
      enum:
      - https
      - http
    domain:
      default: localhost:2368
      description: Your Ghost instance domain and port
tags:
- name: Tiers
  description: Manage membership tiers including creating, reading, and updating tier configurations with pricing and benefits.
paths:
  /tiers/:
    get:
      operationId: adminBrowseTiers
      summary: Browse tiers
      description: Retrieve a paginated list of membership tiers.
      tags:
      - Tiers
      parameters:
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: A list of tiers
          content:
            application/json:
              schema:
                type: object
                properties:
                  tiers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tier'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
      - adminApiToken: []
    post:
      operationId: adminCreateTier
      summary: Create a tier
      description: Create a new membership tier with pricing, benefits, and visibility configuration.
      tags:
      - Tiers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - tiers
              properties:
                tiers:
                  type: array
                  items:
                    $ref: '#/components/schemas/TierInput'
                  minItems: 1
                  maxItems: 1
      responses:
        '201':
          description: Tier created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  tiers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tier'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - adminApiToken: []
    servers:
    - url: https://{site}.ghost.io/ghost/api/admin
      description: Ghost Pro Hosted Site
      variables:
        site:
          default: your-site
          description: Your Ghost site subdomain
    - url: '{protocol}://{domain}/ghost/api/admin'
      description: Self-Hosted Ghost Instance
      variables:
        protocol:
          default: https
          enum:
          - https
          - http
        domain:
          default: localhost:2368
          description: Your Ghost instance domain and port
  /tiers/{id}/:
    get:
      operationId: adminReadTier
      summary: Read a tier by ID
      description: Retrieve a single membership tier by its unique identifier.
      tags:
      - Tiers
      parameters:
      - $ref: '#/components/parameters/resourceId'
      - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: A single tier
          content:
            application/json:
              schema:
                type: object
                properties:
                  tiers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tier'
                    minItems: 1
                    maxItems: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
      - adminApiToken: []
    put:
      operationId: adminUpdateTier
      summary: Update a tier
      description: Update an existing membership tier by its unique identifier.
      tags:
      - Tiers
      parameters:
      - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - tiers
              properties:
                tiers:
                  type: array
                  items:
                    $ref: '#/components/schemas/TierInput'
                  minItems: 1
                  maxItems: 1
      responses:
        '200':
          description: Tier updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  tiers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tier'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
      security:
      - adminApiToken: []
    servers:
    - url: https://{site}.ghost.io/ghost/api/admin
      description: Ghost Pro Hosted Site
      variables:
        site:
          default: your-site
          description: Your Ghost site subdomain
    - url: '{protocol}://{domain}/ghost/api/admin'
      description: Self-Hosted Ghost Instance
      variables:
        protocol:
          default: https
          enum:
          - https
          - http
        domain:
          default: localhost:2368
          description: Your Ghost instance domain and port
components:
  parameters:
    resourceId:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource
      schema:
        type: string
        format: uuid
    page:
      name: page
      in: query
      required: false
      description: Page number for paginated results. Defaults to 1.
      schema:
        type: integer
        minimum: 1
        default: 1
    fields:
      name: fields
      in: query
      required: false
      description: Comma-separated list of fields to return in the response.
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of resources to return per page. Defaults to 15.
      schema:
        oneOf:
        - type: integer
          minimum: 1
        - type: string
          enum:
          - all
        default: 15
    filter:
      name: filter
      in: query
      required: false
      description: Apply fine-grained filters using Ghost's NQL query language.
      schema:
        type: string
    fields_2:
      name: fields
      in: query
      required: false
      description: Comma-separated list of fields to return in the response. Use this to limit the size of the response by only requesting the fields you need.
      schema:
        type: string
    order:
      name: order
      in: query
      required: false
      description: Field and direction to order results by, for example published_at DESC or title ASC.
      schema:
        type: string
    limit_2:
      name: limit
      in: query
      required: false
      description: Maximum number of resources to return per page. Defaults to 15. Use all to return all resources without pagination.
      schema:
        oneOf:
        - type: integer
          minimum: 1
        - type: string
          enum:
          - all
        default: 15
    filter_2:
      name: filter
      in: query
      required: false
      description: Apply fine-grained filters using Ghost's NQL query language. Examples include featured:true, tag:getting-started, visibility:public, and combinations using plus and comma operators.
      schema:
        type: string
  schemas:
    ErrorResponse:
      type: object
      description: Standard Ghost API error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: Human-readable error message
              type:
                type: string
                description: Error type identifier
              context:
                type: string
                description: Additional error context
                nullable: true
    Tier:
      type: object
      description: A membership tier with pricing and benefits configuration.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier
        name:
          type: string
          description: Tier name
        slug:
          type: string
          description: URL-safe slug
        description:
          type: string
          description: Tier description
          nullable: true
        active:
          type: boolean
          description: Whether the tier is active
        type:
          type: string
          description: Tier type
          enum:
          - free
          - paid
        welcome_page_url:
          type: string
          format: uri
          description: Welcome page URL after signup
          nullable: true
        visibility:
          type: string
          description: Public visibility
          enum:
          - public
          - none
        monthly_price:
          type: integer
          description: Monthly price in smallest currency unit
          nullable: true
          minimum: 0
        yearly_price:
          type: integer
          description: Yearly price in smallest currency unit
          nullable: true
          minimum: 0
        currency:
          type: string
          description: ISO 4217 currency code
          nullable: true
          pattern: ^[A-Z]{3}$
        trial_days:
          type: integer
          description: Number of free trial days
          minimum: 0
        benefits:
          type: array
          description: Tier benefits
          items:
            type: string
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
    PaginationMeta:
      type: object
      description: Pagination metadata
      properties:
        pagination:
          type: object
          properties:
            page:
              type: integer
              description: Current page
              minimum: 1
            limit:
              type: integer
              description: Items per page
              minimum: 1
            pages:
              type: integer
              description: Total pages
              minimum: 1
            total:
              type: integer
              description: Total items
              minimum: 0
            next:
              type: integer
              description: Next page number
              nullable: true
            prev:
              type: integer
              description: Previous page number
              nullable: true
    TierInput:
      type: object
      description: Input fields for creating or updating a tier.
      required:
      - name
      properties:
        name:
          type: string
          description: Tier name
        description:
          type: string
          description: Tier description
          nullable: true
        active:
          type: boolean
          description: Whether the tier is active
        visibility:
          type: string
          description: Public visibility
          enum:
          - public
          - none
        welcome_page_url:
          type: string
          format: uri
          description: Welcome page URL
          nullable: true
        monthly_price:
          type: integer
          description: Monthly price in smallest currency unit
          minimum: 0
        yearly_price:
          type: integer
          description: Yearly price in smallest currency unit
          minimum: 0
        currency:
          type: string
          description: ISO 4217 currency code
          pattern: ^[A-Z]{3}$
        trial_days:
          type: integer
          description: Number of free trial days
          minimum: 0
        benefits:
          type: array
          description: Tier benefits
          items:
            type: string
    ErrorResponse_2:
      type: object
      description: Standard Ghost API error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: Human-readable error message
              type:
                type: string
                description: Error type identifier
              context:
                type: string
                description: Additional context about the error
                nullable: true
    Tier_2:
      type: object
      description: A tier represents a membership level in a Ghost publication with associated pricing and benefits.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the tier
        name:
          type: string
          description: Name of the tier
        slug:
          type: string
          description: URL-safe slug for the tier
        description:
          type: string
          description: Description of the tier
          nullable: true
        active:
          type: boolean
          description: Whether the tier is currently active
        type:
          type: string
          description: Type of tier
          enum:
          - free
          - paid
        welcome_page_url:
          type: string
          format: uri
          description: URL of the welcome page shown after signup
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Timestamp when the tier was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the tier was last updated
        visibility:
          type: string
          description: Visibility of the tier
          enum:
          - public
          - none
        monthly_price:
          type: integer
          description: Monthly price in the smallest currency unit (e.g., cents)
          nullable: true
          minimum: 0
        yearly_price:
          type: integer
          description: Yearly price in the smallest currency unit (e.g., cents)
          nullable: true
          minimum: 0
        currency:
          type: string
          description: ISO 4217 currency code
          nullable: true
          pattern: ^[A-Z]{3}$
        trial_days:
          type: integer
          description: Number of free trial days
          minimum: 0
        benefits:
          type: array
          description: List of benefits included in the tier
          items:
            type: string
    PaginationMeta_2:
      type: object
      description: Pagination metadata included in browse responses
      properties:
        pagination:
          type: object
          properties:
            page:
              type: integer
              description: Current page number
              minimum: 1
            limit:
              type: integer
              description: Number of items per page
              minimum: 1
            pages:
              type: integer
              description: Total number of pages
              minimum: 1
            total:
              type: integer
              description: Total number of items across all pages
              minimum: 0
            next:
              type: integer
              description: Next page number, null if on last page
              nullable: true
            prev:
              type: integer
              description: Previous page number, null if on first page
              nullable: true
  responses:
    ValidationError:
      description: Request body validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed or token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized_2:
      description: Authentication failed or API key is missing
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse_2'
  securitySchemes:
    adminApiToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JSON Web Token generated from an Admin API key. The key is split into an ID and secret at the colon separator. The ID is used as the kid header and the secret is used to sign the token with HS256.
    contentApiKey:
      type: apiKey
      in: query
      name: key
      description: Content API key obtained from a custom integration in Ghost Admin. Content API keys are safe for use in browsers and other insecure environments as they only provide access to public data.
x-refined-from:
- ghost-org-admin-api-openapi.yml
- ghost-org-content-api-openapi.yml