Spree Commerce Taxons API

The Taxons API from Spree Commerce — 5 operation(s) for taxons.

Operations 8

GET /api/v2/platform/taxons Return a list of Taxons #
POST /api/v2/platform/taxons Create a Taxon #
GET /api/v2/platform/taxons/{id} Return a Taxon #
PATCH /api/v2/platform/taxons/{id} Update a Taxon #
DELETE /api/v2/platform/taxons/{id} Delete a Taxon #
PATCH /api/v2/platform/taxons/{id}/reposition Reposition a Taxon #
GET /api/v2/storefront/taxons List all Taxons #
GET /api/v2/storefront/taxons/{taxon_permalink} Retrieve a Taxon #

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/spree-commerce-taxons-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

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.

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

OpenAPI Specification

spree-commerce-taxons-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Spree Commerce Taxons API
  version: '1.0'
  description: 'Operations tagged Taxons across 2 of this provider''s published API definitions: spree-commerce-platform-api-openapi.yml, spree-commerce-storefront-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
- url: https://demo.spreecommerce.org
  description: demo
- url: http://localhost:3000
  description: localhost
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'
    servers:
    - url: http://{defaultHost}
      variables:
        defaultHost:
          default: localhost:3000
  /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'
    servers:
    - url: http://{defaultHost}
      variables:
        defaultHost:
          default: localhost:3000
  /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'
    servers:
    - url: http://{defaultHost}
      variables:
        defaultHost:
          default: localhost:3000
  /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
    servers:
    - url: https://demo.spreecommerce.org
      description: demo
    - url: http://localhost:3000
      description: localhost
  /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
    servers:
    - url: https://demo.spreecommerce.org
      description: demo
    - url: http://localhost:3000
      description: localhost
components:
  schemas:
    create_taxon_params:
      type: object
      properties:
        taxon:
          type: object
          required:
          - name
          - taxonomy_id
          properties:
            taxonomy_id:
              type: string
            parent_id:
              type: string
            name:
              type: string
            public_metadata:
              type: object
              example:
                ability_to_recycle: 90%
            private_metadata:
              type: object
              example:
                profitability: 2
      required:
      - taxon
      x-internal: false
    resource_properties:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        attributes:
          type: object
        relationships:
          type: object
      required:
      - id
      - type
      - attributes
      x-internal: false
    update_taxon_params:
      type: object
      properties:
        taxon:
          type: object
          properties:
            taxonomy_id:
              type: string
            parent_id:
              type: string
            name:
              type: string
            public_metadata:
              type: object
            private_metadata:
              type: object
      required:
      - taxon
      x-internal: false
    resources_list:
      type: object
      properties:
        data:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/resource_properties'
        meta:
          type: object
          properties:
            count:
              type: integer
            total_count:
              type: integer
            total_pages:
              type: integer
          required:
          - count
          - total_count
          - total_pages
        links:
          type: object
          properties:
            self:
              type: string
            next:
              type: string
            prev:
              type: string
            last:
              type: string
            first:
              type: string
          required:
          - self
          - next
          - prev
          - last
          - first
      required:
      - data
      - meta
      - links
      x-internal: false
    validation_errors:
      type: object
      properties:
        error:
          type: string
        errors:
          type: object
      required:
      - error
      - errors
      x-internal: false
    resource:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/resource_properties'
      required:
      - data
      x-internal: false
    error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
      x-internal: false
    taxon_reposition:
      type: object
      properties:
        taxon:
          type: object
          required:
          - new_parent_id
          - new_position_idx
          properties:
            new_parent_id:
              type: integer
              example: 1
              description: The ID of the new target parent Taxon.
            new_position_idx:
              type: integer
              example: 1
              description: The new index position of the Taxon within the parent Taxon.
      required:
      - taxon
      title: Reposition a Taxon
      x-internal: false
    Product:
      type: object
      title: Product
      x-internal: false
      properties:
        id:
          type: string
          example: '1'
        type:
          type: string
          default: product
        attributes:
          type: object
          properties:
            name:
              type: string
              example: Example product
            description:
              type:
              - string
              - 'null'
              example: Example description
            available_on:
              type:
              - string
              - 'null'
              example: '2012-10-17T03:43:57Z'
            slug:
              type: string
              example: example-product
            price:
              type:
              - string
              - 'null'
              example: '15.99'
            currency:
              type: string
              example: USD
            display_price:
              type:
              - string
              - 'null'
              example: $15.99
            purchasable:
              type: boolean
              description: Indicates if any of Variants are in stock or backorderable
            in_stock:
              type: boolean
              description: Indicates if any of Variants are in stock
            backorderable:
              type: boolean
              description: Indicates if any of Variants are backeorderable
            meta_description:
              type:
              - string
              - 'null'
              example: Example product
            meta_keywords:
              type:
              - string
              - 'null'
              example: example, product
            updated_at:
              $ref: '#/components/schemas/Timestamp'
            sku:
              type: string
              example: 9238-WS
            available:
              type: boolean
            compare_at_price:
              type:
              - string
              - 'null'
              example: '49.99'
            display_compare_at_price:
              type:
              - string
              - 'null'
              example: $49.99
            localized_slugs:
              type: object
              description: Provides product's slugs in other locales
            tags:
              type: array
              items:
                type: string
              description: List of tags associated with the product
            labels:
              type: array
              items:
                type: string
              description: List of labels associated with the product
        relationships:
          type: object
          properties:
            variants:
              type: object
              description: List of Product Variants, excluding Master Variant
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            option_types:
              type: object
              description: List of Product Option Types
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            product_properties:
              type: object
              description: List of Product Properties
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            taxons:
              type: object
              description: List of Taxons associated with this Product
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Relation'
            images:
              type: object
              description: List of Images associated with th

# --- 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