Spree Commerce Post Categories API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Storefront Post Categories API
  description: 'Storefront API is a modern REST API based on the [JSON API spec](https://jsonapi.org/) which provides you with all the necessary endpoints to build amazing user interfaces either in JavaScript frameworks or native mobile libraries.


    Import to [Postman](https://raw.githubusercontent.com/spree/spree/main/docs/api-reference/storefront.yaml)'
  contact:
    name: Vendo Connect Inc.
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  license:
    name: BSD-3-Clause
    url: https://github.com/spree/spree/blob/main/LICENSE.md
servers:
- url: https://demo.spreecommerce.org
  description: demo
- url: http://localhost:3000
  description: localhost
tags:
- name: Post Categories
paths:
  /api/v2/storefront/post_categories:
    get:
      summary: List all Post Categories
      description: Returns a list of Post Categories. This endpoint is only available in Spree 5.2 or later.
      tags:
      - Post Categories
      operationId: post-categories-list
      parameters:
      - $ref: '#/components/parameters/FilterByIds'
      - in: query
        name: filter[title]
        schema:
          type: string
        example: News
        description: Filter Post Categories by title
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - in: query
        name: sort
        schema:
          type: string
          enum:
          - id
          - -id
          - title
          - -title
          - created_at
          - -created_at
          - updated_at
          - -updated_at
        example: title
        description: 'Sort post categories by attribute. Prefix with "-" for descending order. Available options: id, title, created_at, updated_at'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PostCategory'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
                  links:
                    $ref: '#/components/schemas/ListLinks'
              examples:
                success:
                  value:
                    data:
                    - id: '1'
                      type: post_category
                      attributes:
                        title: Resources
                        slug: resources
                        created_at: '2025-08-11T20:58:24.354Z'
                        updated_at: '2025-08-11T20:58:24.354Z'
                        description: null
                      relationships: {}
                    - id: '2'
                      type: post_category
                      attributes:
                        title: Articles
                        slug: articles
                        created_at: '2025-08-11T20:58:24.365Z'
                        updated_at: '2025-08-11T20:58:24.365Z'
                        description: null
                      relationships: {}
                    - id: '3'
                      type: post_category
                      attributes:
                        title: News
                        slug: news
                        created_at: '2025-08-11T20:58:24.375Z'
                        updated_at: '2025-08-11T20:58:24.375Z'
                        description: null
                      relationships: {}
                    meta:
                      count: 3
                      total_count: 3
                      total_pages: 1
                    links:
                      self: http://localhost:3000/api/v2/storefront/post_categories
                      next: http://localhost:3000/api/v2/storefront/post_categories?page=1
                      prev: http://localhost:3000/api/v2/storefront/post_categories?page=1
                      last: http://localhost:3000/api/v2/storefront/post_categories?page=1
                      first: http://localhost:3000/api/v2/storefront/post_categories?page=1
  /api/v2/storefront/post_categories/{id}:
    get:
      summary: Retrieve a Post Category
      description: Returns the details of a specified Post Category, including related posts. You can use either the category slug or ID. This endpoint is only available in Spree 5.2 or later.
      tags:
      - Post Categories
      operationId: show-post-category
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: news
        description: Post Category slug or ID
      - in: query
        name: include
        schema:
          type: string
        example: posts
        description: 'Include related resources (available: posts)'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PostCategory'
              examples:
                success:
                  value:
                    data:
                      id: '3'
                      type: post_category
                      attributes:
                        title: News
                        slug: news
                        created_at: '2025-08-11T20:58:24.375Z'
                        updated_at: '2025-08-11T20:58:24.375Z'
                        description: null
                      relationships:
                        posts:
                          data:
                          - id: '1'
                            type: post
        '404':
          $ref: '#/components/responses/404NotFound'
components:
  schemas:
    PostCategory:
      type: object
      title: Post Category
      description: Post Category represents a category for organizing blog posts or news articles.
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: post_category
        attributes:
          type: object
          properties:
            title:
              type: string
              example: News
              description: Title of the post category
            slug:
              type: string
              example: news
              description: URL-friendly identifier for the post category
            created_at:
              $ref: '#/components/schemas/Timestamp'
            updated_at:
              $ref: '#/components/schemas/Timestamp'
            description:
              type:
              - string
              - 'null'
              example: null
              description: Description of the post category
        relationships:
          type: object
          properties:
            posts:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        example: '1'
                      type:
                        type: string
                        example: post
          required:
          - title
          - slug
          - created_at
          - updated_at
      required:
      - id
      - type
      - attributes
    Timestamp:
      type: string
      format: date-time
      example: '2020-02-16T07:14:54.617Z'
      x-internal: false
      title: Time Stamp
      x-examples:
        example-1: '2020-02-16T07:14:54.617Z'
    ListMeta:
      type: object
      x-internal: false
      title: Pagination Meta
      properties:
        count:
          type: number
          example: 7
          description: Number of items on the current listing
        total_count:
          type: number
          example: 145
          description: Number of all items matching the criteria
        total_pages:
          type: number
          example: 10
          description: Number of all pages containing items matching the criteria
    ListLinks:
      x-internal: false
      type: object
      title: Pagination Links
      properties:
        self:
          type: string
          description: URL to the current page of the listing
        next:
          type: string
          description: URL to the next page of the listing
        prev:
          type: string
          description: URL to the previous page of the listing
        last:
          type: string
          description: URL to the last page of the listing
        first:
          type: string
          description: URL to the first page of the listing
  parameters:
    PageParam:
      name: page
      in: query
      description: Number of requested page when paginating collection
      schema:
        type: integer
      example: 1
    FilterByIds:
      in: query
      name: filter[ids]
      schema:
        type: string
      example: 1,2,3
      description: Fetch only resources with corresponding IDs
    PerPageParam:
      name: per_page
      in: query
      description: Number of requested records per page when paginating collection
      schema:
        type: integer
      example: 25
  responses:
    404NotFound:
      description: 404 Not Found - Resource not found.
      content:
        application/vnd.api+json:
          schema:
            properties:
              error:
                type: string
                example: The resource you were looking for could not be found.
                default: The resource you were looking for could not be found.
          examples:
            404 Example:
              value:
                error: The resource you were looking for could not be found.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'User token to authorize Cart and Checkout requests.


        It is required to associate Cart with the User.'
    orderToken:
      type: apiKey
      in: header
      description: 'Order token to authorize Cart and Checkout requests.


        [How to obtain X-Spree-Order-Token](../authentication#for-guest-users)'
      name: X-Spree-Order-Token