Spree Commerce Taxons API

openapi: 3.0.3
info:
  title: Admin Account / Address Taxons API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Validation failed\",\n    \"details\": { \"name\": [\"can't be blank\"] }\n  }\n}\n```\n"
  version: v3
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Taxons
paths:
  /api/v2/platform/taxons:
    get:
      summary: Return a list of Taxons
      tags:
      - Taxons
      security:
      - bearer_auth: []
      description: Returns a list of Taxons
      operationId: taxons-list
      parameters:
      - name: page
        in: query
        example: 1
        schema:
          type: integer
      - name: per_page
        in: query
        example: 50
        schema:
          type: integer
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: taxonomy,parent,children
        schema:
          type: string
      - name: filter[taxonomy_id_eq]
        in: query
        description: ''
        example: '1'
        schema:
          type: string
      - name: filter[name_cont]
        in: query
        description: ''
        example: Shirts
        schema:
          type: string
      responses:
        '200':
          description: Records returned
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                    - id: '38'
                      type: taxon
                      attributes:
                        position: 0
                        name: Shorts
                        permalink: taxonomy-25/shorts
                        lft: 2
                        rgt: 3
                        description: null
                        created_at: '2022-11-08T19:35:49.576Z'
                        updated_at: '2022-11-08T19:35:49.581Z'
                        meta_title: null
                        meta_description: null
                        meta_keywords: null
                        depth: 1
                        public_metadata: {}
                        private_metadata: {}
                        pretty_name: taxonomy_25 -> Shorts
                        seo_title: Shorts
                        is_root: false
                        is_child: true
                        is_leaf: true
                      relationships:
                        parent:
                          data:
                            id: '37'
                            type: taxon
                        taxonomy:
                          data:
                            id: '25'
                            type: taxonomy
                        children:
                          data: []
                        image:
                          data:
                            id: '89'
                            type: taxon_image
                    - id: '39'
                      type: taxon
                      attributes:
                        position: 0
                        name: taxon_13
                        permalink: taxonomy-25/taxon-13
                        lft: 4
                        rgt: 5
                        description: null
                        created_at: '2022-11-08T19:35:49.603Z'
                        updated_at: '2022-11-08T19:35:49.606Z'
                        meta_title: null
                        meta_description: null
                        meta_keywords: null
                        depth: 1
                        public_metadata: {}
                        private_metadata: {}
                        pretty_name: taxonomy_25 -> taxon_13
                        seo_title: taxon_13
                        is_root: false
                        is_child: true
                        is_leaf: true
                      relationships:
                        parent:
                          data:
                            id: '37'
                            type: taxon
                        taxonomy:
                          data:
                            id: '25'
                            type: taxonomy
                        children:
                          data: []
                        image:
                          data:
                            id: '90'
                            type: taxon_image
                    - id: '40'
                      type: taxon
                      attributes:
                        position: 0
                        name: taxon_14
                        permalink: taxonomy-25/taxon-14
                        lft: 6
                        rgt: 7
                        description: null
                        created_at: '2022-11-08T19:35:49.625Z'
                        updated_at: '2022-11-08T19:35:49.628Z'
                        meta_title: null
                        meta_description: null
                        meta_keywords: null
                        depth: 1
                        public_metadata: {}
                        private_metadata: {}
                        pretty_name: taxonomy_25 -> taxon_14
                        seo_title: taxon_14
                        is_root: false
                        is_child: true
                        is_leaf: true
                      relationships:
                        parent:
                          data:
                            id: '37'
                            type: taxon
                        taxonomy:
                          data:
                            id: '25'
                            type: taxonomy
                        children:
                          data: []
                        image:
                          data:
                            id: '91'
                            type: taxon_image
                    - id: '37'
                      type: taxon
                      attributes:
                        position: 0
                        name: taxonomy_25
                        permalink: taxonomy-25
                        lft: 1
                        rgt: 8
                        description: null
                        created_at: '2022-11-08T19:35:49.552Z'
                        updated_at: '2022-11-08T19:35:49.636Z'
                        meta_title: null
                        meta_description: null
                        meta_keywords: null
                        depth: 0
                        public_metadata: {}
                        private_metadata: {}
                        pretty_name: taxonomy_25
                        seo_title: taxonomy_25
                        is_root: true
                        is_child: false
                        is_leaf: false
                      relationships:
                        parent:
                          data: null
                        taxonomy:
                          data:
                            id: '25'
                            type: taxonomy
                        children:
                          data:
                          - id: '38'
                            type: taxon
                          - id: '39'
                            type: taxon
                          - id: '40'
                            type: taxon
                        image:
                          data: null
                    meta:
                      count: 4
                      total_count: 4
                      total_pages: 1
                    links:
                      self: http://www.example.com/api/v2/platform/taxons?page=1&per_page=&include=&filter[taxonomy_id_eq]=&filter[name_cont]=
                      next: http://www.example.com/api/v2/platform/taxons?filter%5Bname_cont%5D=&filter%5Btaxonomy_id_eq%5D=&include=&page=1&per_page=
                      prev: http://www.example.com/api/v2/platform/taxons?filter%5Bname_cont%5D=&filter%5Btaxonomy_id_eq%5D=&include=&page=1&per_page=
                      last: http://www.example.com/api/v2/platform/taxons?filter%5Bname_cont%5D=&filter%5Btaxonomy_id_eq%5D=&include=&page=1&per_page=
                      first: http://www.example.com/api/v2/platform/taxons?filter%5Bname_cont%5D=&filter%5Btaxonomy_id_eq%5D=&include=&page=1&per_page=
              schema:
                $ref: '#/components/schemas/resources_list'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
    post:
      summary: Create a Taxon
      tags:
      - Taxons
      security:
      - bearer_auth: []
      description: Creates a Taxon
      operationId: create-taxon
      parameters:
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: taxonomy,parent,children
        schema:
          type: string
      responses:
        '201':
          description: Record created
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '47'
                      type: taxon
                      attributes:
                        position: 0
                        name: taxon_17
                        permalink: taxonomy-27/taxon-17
                        lft: 4
                        rgt: 5
                        description: null
                        created_at: '2022-11-08T19:35:50.279Z'
                        updated_at: '2022-11-08T19:35:50.283Z'
                        meta_title: null
                        meta_description: null
                        meta_keywords: null
                        depth: 1
                        public_metadata: {}
                        private_metadata: {}
                        pretty_name: taxonomy_27 -> taxon_17
                        seo_title: taxon_17
                        is_root: false
                        is_child: true
                        is_leaf: true
                      relationships:
                        parent:
                          data:
                            id: '45'
                            type: taxon
                        taxonomy:
                          data:
                            id: '27'
                            type: taxonomy
                        children:
                          data: []
                        image:
                          data: null
              schema:
                $ref: '#/components/schemas/resource'
        '422':
          description: Invalid request
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: Name can't be blank and Taxonomy can't be blank
                    errors:
                      name:
                      - can't be blank
                      taxonomy:
                      - can't be blank
              schema:
                $ref: '#/components/schemas/validation_errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_taxon_params'
  /api/v2/platform/taxons/{id}:
    get:
      summary: Return a Taxon
      tags:
      - Taxons
      security:
      - bearer_auth: []
      description: Returns a Taxon
      operationId: show-taxon
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: taxonomy,parent,children
        schema:
          type: string
      responses:
        '200':
          description: Record found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '52'
                      type: taxon
                      attributes:
                        position: 0
                        name: taxon_18
                        permalink: taxonomy-29/taxon-18
                        lft: 4
                        rgt: 5
                        description: null
                        created_at: '2022-11-08T19:35:50.654Z'
                        updated_at: '2022-11-08T19:35:50.657Z'
                        meta_title: null
                        meta_description: null
                        meta_keywords: null
                        depth: 1
                        public_metadata: {}
                        private_metadata: {}
                        pretty_name: taxonomy_29 -> taxon_18
                        seo_title: taxon_18
                        is_root: false
                        is_child: true
                        is_leaf: true
                      relationships:
                        parent:
                          data:
                            id: '50'
                            type: taxon
                        taxonomy:
                          data:
                            id: '29'
                            type: taxonomy
                        children:
                          data: []
                        products:
                          data: []
                        image:
                          data:
                            id: '98'
                            type: taxon_image
              schema:
                $ref: '#/components/schemas/resource'
        '404':
          description: Record not found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The resource you were looking for could not be found.
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
    patch:
      summary: Update a Taxon
      tags:
      - Taxons
      security:
      - bearer_auth: []
      description: Updates a Taxon
      operationId: update-taxon
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: 'Select which associated resources you would like to fetch, see: <a href="https://jsonapi.org/format/#fetching-includes">https://jsonapi.org/format/#fetching-includes</a>'
        example: taxonomy,parent,children
        schema:
          type: string
      responses:
        '200':
          description: Record updated
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '60'
                      type: taxon
                      attributes:
                        position: 0
                        name: T-Shirts
                        permalink: taxonomy-32/taxon-20
                        lft: 4
                        rgt: 5
                        description: null
                        created_at: '2022-11-08T19:35:51.420Z'
                        updated_at: '2022-11-08T19:35:51.665Z'
                        meta_title: null
                        meta_description: null
                        meta_keywords: null
                        depth: 1
                        public_metadata:
                          profitability: 3
                        private_metadata: {}
                        pretty_name: taxonomy_32 -> T-Shirts
                        seo_title: T-Shirts
                        is_root: false
                        is_child: true
                        is_leaf: true
                      relationships:
                        parent:
                          data:
                            id: '58'
                            type: taxon
                        taxonomy:
                          data:
                            id: '32'
                            type: taxonomy
                        children:
                          data: []
                        image:
                          data:
                            id: '103'
                            type: taxon_image
              schema:
                $ref: '#/components/schemas/resource'
        '422':
          description: Invalid request
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: Name can't be blank
                    errors:
                      name:
                      - can't be blank
              schema:
                $ref: '#/components/schemas/validation_errors'
        '404':
          description: Record not found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The resource you were looking for could not be found.
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_taxon_params'
    delete:
      summary: Delete a Taxon
      tags:
      - Taxons
      security:
      - bearer_auth: []
      description: Deletes a Taxon
      operationId: delete-taxon
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Record deleted
        '404':
          description: Record not found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The resource you were looking for could not be found.
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
  /api/v2/platform/taxons/{id}/reposition:
    patch:
      summary: Reposition a Taxon
      tags:
      - Taxons
      security:
      - bearer_auth: []
      operationId: reposition-taxon
      description: Reposition a Taxon
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Record updated
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    data:
                      id: '79'
                      type: taxon
                      attributes:
                        position: 0
                        name: taxon_25
                        permalink: taxonomy-39/shorts/taxon-25
                        lft: 3
                        rgt: 4
                        description: null
                        created_at: '2022-11-08T19:35:53.074Z'
                        updated_at: '2022-11-08T19:35:53.324Z'
                        meta_title: null
                        meta_description: null
                        meta_keywords: null
                        depth: 2
                        public_metadata: {}
                        private_metadata: {}
                        pretty_name: taxonomy_39 -> Shorts -> taxon_25
                        seo_title: taxon_25
                        is_root: false
                        is_child: true
                        is_leaf: true
                      relationships:
                        parent:
                          data:
                            id: '78'
                            type: taxon
                        taxonomy:
                          data:
                            id: '39'
                            type: taxonomy
                        children:
                          data: []
                        image:
                          data:
                            id: '115'
                            type: taxon_image
              schema:
                $ref: '#/components/schemas/resource'
        '404':
          description: Record not found
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The resource you were looking for could not be found.
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Authentication Failed
          content:
            application/vnd.api+json:
              examples:
                Example:
                  value:
                    error: The access token is invalid
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/taxon_reposition'
  /api/v2/storefront/taxons:
    get:
      description: Returns a list of Taxons. [Read more about Taxons](/developer/core-concepts/products#taxons-and-taxonomies)
      tags:
      - Taxons
      operationId: taxons-list
      parameters:
      - $ref: '#/components/parameters/FilterByIds'
      - $ref: '#/components/parameters/FilterByName'
      - in: query
        name: filter[parent_id]
        schema:
          type: string
        example: '1'
        description: Fetch children nodes of specified Taxon
      - in: query
        name: filter[parent_permalink]
        schema:
          type: string
        example: clothes
        description: Fetch children nodes of specified Taxon permalink
      - in: query
        name: filter[taxonomy_id]
        schema:
          type: string
        example: '1'
        description: Fetch Taxons in a specified Taxonomy
      - in: query
        name: filter[roots]
        schema:
          type: boolean
        example: false
        description: Fetch only root Taxons (Taxonomies)
      - in: query
        name: filter[vendor_id]
        schema:
          type: string
        example: '1'
        description: Fetch only Taxons that have products of a selected Vendor
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/TaxonIncludeParam'
      - $ref: '#/components/parameters/SparseFieldsTaxon'
      responses:
        '200':
          $ref: '#/components/responses/TaxonList'
      summary: List all Taxons
  /api/v2/storefront/taxons/{taxon_permalink}:
    get:
      description: Returns the details of a specified taxon.
      tags:
      - Taxons
      operationId: show-taxon
      parameters:
      - $ref: '#/components/parameters/TaxonPermalink'
      - $ref: '#/components/parameters/TaxonIncludeParam'
      - $ref: '#/components/parameters/SparseFieldsTaxon'
      responses:
        '200':
          $ref: '#/components/responses/Taxon'
        '404':
          $ref: '#/components/responses/404NotFound'
      summary: Retrieve a Taxon
components:
  parameters:
    TaxonIncludeParam:
      name: include
      in: query
      schema:
        type: string
      description: Specify the related resources you would like to receive in the response body. [More Information](https://jsonapi.org/format/#fetching-includes).
      example: parent,taxonomy,children,image,products
    SparseFieldsTaxon:
      in: query
      name: fields[taxon]
      example: name,pretty_name,permalink
      description: Specify the fields you would like returned in the response body. [More information](https://jsonapi.org/format/#fetching-sparse-fieldsets).
      schema:
        type: string
    PageParam:
      name: page
      in: query
      description: Number of requested page when paginating collection
      schema:
        type: integer
      example: 1
    PerPageParam:
      name: per_page
      in: query
      description: Number of requested records per page when paginating collection
      schema:
        type: integer
      example: 25
    FilterByName:
      in: query
      name: filter[name]
      schema:
        type: string
      example: rails
      description: Find resources with matching name (supports wild-card, partial-word match search)
    FilterByIds:
      in: query
      name: filter[ids]
      schema:
        type: string
      example: 1,2,3
      description: Fetch only resources with corresponding IDs
    TaxonPermalink:
      name: taxon_permalink
      in: path
      required: true
      description: Specify the taxon using the permalink or taxon ID.
      schema:
        type: string
      example: categories/women
  schemas:
    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
    resource_properties:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        attributes:
          type: object
        relationships:
          type: object
      required:
      - id
      - type
      - attributes
      x-internal: false
    TaxonIncludes:
      x-internal: false
      title: Taxon Includes
      anyOf:
      - $ref: '#/components/schemas/Product'
      - $ref: '#/components/schemas/TaxonImage'
      - $ref: '#/components/schemas/Taxonomy'
    ImageStyle:
      x-internal: false
      title: Image Style
      type: object
      properties:
        url:
          type: string
          example: http://localhost:3000/rails/active_storage/disk/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJbWQyWVhKcFlXNTBjeTltWm1sMmRURlNORFpZWjJaSFpYUkdZMjk2WWsxM1RHWXZNVGs1T1RCak5XVmlNamN4TlRnd1pqVTBabUpqTWpCbFkyVXhZMlZpTTJFd05ERTJZemMzT0dKaE5tSTFNREkyT0dKaFpqa3paV1JtWTJWaE16aGxaQVk2QmtWVSIsImV4cCI6IjIwMTgtMDYtMjRUMTM6NTk6NTguOTY5WiIsInB1ciI6ImJsb2Jfa2V5In19--5e9ff358dc747f73754e332678c5762114ac6f3f/ror_jr_spaghetti.jpeg?content_type=image%2Fjpeg&disposition=inline%3B+filename%3D%22ror_jr_spaghetti.jpeg%22%3B+filename%2A%3DUTF-8%27%27ror_jr_spaghetti.jpeg
          description: Absolute URL of the uploaded image in selected style (width/height)
        width:
          type: integer
          example: 1920
          description: Actual width of image
        height:
          type: integer
          example: 1080
          description: Actual height of image
    Taxon:
      title: Taxon
      type: object
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: taxon
        attributes:
          type: object
          properties:
            name:
              type: string
              example: T-shirts
            pretty_name:
              type: string
              example: Clothes > T-shirts
            permalink:
              type: string
              example: t-shirts
            seo_title:
              type: string
              example: Clothes - T-shirts
            meta_title:
              type: string
              example: T-shirts
              nullable: true
            meta_description:
              type: string
              example: 'A list of cool t-shirts '
              nullable: true
            meta_keywords:
              type: string
              example: t-shirts, cool
              nullable: true
            left:
              type: integer
              example: 1
            right:
              type: integer
              example: 2
            position:
              type: integer
              example: 0
            depth:
              type: integer
              example: 1
              nullable: true
            is_root:
              type: boolean
              example: true
              description: Indicates if the Taxon is the root node of this Taxonomy tree
            is_child:
              type: boolean
              example: true
              description: Returns true is this is a child node of this Taxonomy tree
            is_leaf:
              type: boolean
              example: false
              description: Returns true if this is the end of a branch of this Taxonomy tree
            updated_at:
              type: string
              example: '2018-06-18T10:57:29.704Z'
            localized_slugs:
              type: object
              description: Provides taxon's slugs in other locales
        relationships:
          type: object
          properties:
            parent:
              type: object
              description: Parent node
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            children:
              type: object
              description: List of child nodes
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            taxonomy:
              type: object
              description: Taxonomy associated with this Taxon
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            image:
              type: object
              description: Image associated with Taxon
              properties:
                data:
                  $ref: '#/components/schemas/Relation'
            products:
              type: object
              description: List of active and available Products associated with this Taxon
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
      required:
      - id
      - type
      - attributes
      - relationships
    Product:
      type: object
      title: Product
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: product
        attributes:
          type: object
          properties:
            na

# --- truncated at 32 KB (164 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spree-commerce/refs/heads/main/openapi/spree-commerce-taxons-api-openapi.yml