APIDeveloperUserRelease NotesDemoContact Us
  • Api

    • Summary
    • Address
    • Checkouts
    • Countries
    • Customer Returns
    • Line Items
    • Option Types
    • Option Values
    • Orders
    • Payments
    • Product Images
    • Product Properties
    • Products
    • Return Authorizations
    • Shipments
    • States
    • Stock Items
    • Stock Locations
    • Stock Movements
    • Taxonomies
    • Users
    • Variants
    • Zones

Table Of Contents

IndexParametersResponseSearchResponseSorting resultsShowResponseCreateResponseUpdateResponseDeleteResponseList taxonsParametersResponseA single taxonResponseTaxon CreateResponseTaxon UpdateResponseTaxon DeleteResponse

Taxonomies

Index

To get a list of all the taxonomies, including their root nodes and the immediate children for the root node, make a request like this:

GET /api/v1/taxonomies

Parameters

page:

The page number of taxonomy to display.

per_page:

The number of taxonomies to return per page

set:

Displays the complete expanded taxonomy tree if set to nested.

Response

Status:
200 OK
{
"taxonomies": [
{
"id": 1,
"name": "Brand",
"root": {
"id": 2,
"name": "Ruby on Rails",
"pretty_name": "Ruby on Rails",
"permalink": "brands/ruby-on-rails",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "Ruby on Rails",
"meta_description": "Ruby on Rails",
"taxons": [
{
"id": 3,
"name": "T-Shirts",
"pretty_name": "T-Shirts",
"permalink": "brands/t-shirts",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "T-Shirts",
"meta_description": "T-Shirts",
"taxons": []
}
]
}
}
],
"count": 25,
"current_page": 1,
"pages": 5
}

Search

To search for a particular taxonomy, make a request like this:

GET /api/v1/taxonomies?q[name_cont]=brand

The searching API is provided through the Ransack gem which Spree depends on. The name_cont here is called a predicate, and you can learn more about them by reading about Predicates on the Ransack wiki.

The search results are paginated.

Response

Status:
200 OK
{
"taxonomies": [
{
"id": 1,
"name": "Brand",
"root": {
"id": 2,
"name": "Ruby on Rails",
"pretty_name": "Ruby on Rails",
"permalink": "brands/ruby-on-rails",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "Ruby on Rails",
"meta_description": "Ruby on Rails",
"taxons": [
{
"id": 3,
"name": "T-Shirts",
"pretty_name": "T-Shirts",
"permalink": "brands/t-shirts",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "T-Shirts",
"meta_description": "T-Shirts",
"taxons": []
}
]
}
}
],
"count": 25,
"current_page": 1,
"pages": 5
}

Sorting results

Results can be returned in a specific order by specifying which field to sort by when making a request.

GET /api/v1/taxonomies?q[s]=name%20asc

It is also possible to sort results using an associated object’s field.

GET /api/v1/taxonomies?q[s]=root_name%20desc

Show

To get information for a single taxonomy, including its root node and the immediate children of the root node, make a request like this:

GET /api/v1/taxonomies/1

Response

Status:
200 OK
{
"id": 1,
"name": "Brand",
"root": {
"id": 2,
"name": "Ruby on Rails",
"pretty_name": "Ruby on Rails",
"permalink": "brands/ruby-on-rails",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "Ruby on Rails",
"meta_description": "Ruby on Rails",
"taxons": [
{
"id": 3,
"name": "T-Shirts",
"pretty_name": "T-Shirts",
"permalink": "brands/t-shirts",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "T-Shirts",
"meta_description": "T-Shirts",
"taxons": []
}
]
}
}

Create

This action is only accessible by an admin user.

To create a taxonomy, make a request like this:

POST /api/v1/taxonomies

For instance, if you want to create a taxonomy with the name ”Brands”, make this request:

POST /api/v1/taxonomies?taxonomy[name]=Brand

If you’re creating a taxonomy without a root taxon, a root taxon will automatically be created for you with the same name as the taxon.

Response

Status:
201 Created
{
"id": 1,
"name": "Brand",
"root": {
"id": 2,
"name": "Ruby on Rails",
"pretty_name": "Ruby on Rails",
"permalink": "brands/ruby-on-rails",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "Ruby on Rails",
"meta_description": "Ruby on Rails",
"taxons": []
}
}

Update

This action is only accessible by an admin user.

To update a taxonomy, make a request like this:

PUT /api/v1/taxonomies/1

For instance, to update a taxonomy’s name, make this request:

PUT /api/v1/taxonomies/1?taxonomy[name]=Brand

Response

Status:
200 OK
{
"id": 1,
"name": "Brand",
"root": {
"id": 2,
"name": "Ruby on Rails",
"pretty_name": "Ruby on Rails",
"permalink": "brands/ruby-on-rails",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "Ruby on Rails",
"meta_description": "Ruby on Rails",
"taxons": [
{
"id": 3,
"name": "T-Shirts",
"pretty_name": "T-Shirts",
"permalink": "brands/t-shirts",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "T-Shirts",
"meta_description": "T-Shirts",
"taxons": []
}
]
}
}

Delete

This action is only accessible by an admin user.

To delete a taxonomy, make a request like this:

DELETE /api/v1/taxonomies/1

Response

Status:
204 No Content

List taxons

To get a list for all taxons underneath the root taxon for a taxonomy (and their children) for a taxonomy, make this request:

GET /api/v1/taxonomies/1/taxons

Parameters

without_children:

Displays only immediate children of taxons if set to true.

Response

Status:
200 OK
{
"taxons": [
{
"id": 2,
"name": "Ruby on Rails",
"pretty_name": "Ruby on Rails",
"permalink": "brands/ruby-on-rails",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "Ruby on Rails",
"meta_description": "Ruby on Rails",
"taxons": [
{
"id": 3,
"name": "T-Shirts",
"pretty_name": "T-Shirts",
"permalink": "brands/t-shirts",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "T-Shirts",
"meta_description": "T-Shirts",
"taxons": []
}
]
}
],
"count": 7,
"total_count": 7,
"current_page": 1,
"per_page": 25,
"pages": 1
}

A single taxon

To see information about a taxon and its immediate children, make a request like this:

GET /api/v1/taxonomies/1/taxons/1

Response

Status:
200 OK
{
"id": 2,
"name": "Ruby on Rails",
"pretty_name": "Ruby on Rails",
"permalink": "brands/ruby-on-rails",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "Ruby on Rails",
"meta_description": "Ruby on Rails",
"taxons": [
{
"id": 3,
"name": "T-Shirts",
"pretty_name": "T-Shirts",
"permalink": "brands/t-shirts",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "T-Shirts",
"meta_description": "T-Shirts",
"taxons": []
}
]
}

Taxon Create

This action is only accessible by an admin user.

To create a taxon, make a request like this:

POST /api/v1/taxonomies/1/taxons

To create a new taxon with the name “Brands”, make this request:

POST /api/v1/taxonomies/1/taxons?taxon[name]=Brands

Response

Status:
201 Created
{
"id": 2,
"name": "Brands",
"pretty_name": "Brands",
"permalink": "brands/brands",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "Brands",
"meta_description": "Brands",
"taxons": []
}

Taxon Update

This action is only accessible by an admin user.

To update a taxon, make a request like this:

PUT /api/v1/taxonomies/1/taxons/1

For example, to update the taxon’s name to “Brand”, make this request:

PUT /api/v1/taxonomies/1/taxons/1?taxon[name]=Brand

Response

Status:
200 OK
{
"id": 2,
"name": "Brands",
"pretty_name": "Brands",
"permalink": "brands/brands",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "Brands",
"meta_description": "Brands",
"taxons": [
{
"id": 3,
"name": "T-Shirts",
"pretty_name": "T-Shirts",
"permalink": "brands/t-shirts",
"parent_id": 1,
"taxonomy_id": 1,
"meta_title": "T-Shirts",
"meta_description": "T-Shirts",
"taxons": []
}
]
}

Taxon Delete

This action is only accessible by an admin user.

To delete a taxon, make a request like this:

DELETE /api/v1/taxonomies/1/taxons/1

This will cause all child taxons to be deleted as well.

Response

Status:
204 No Content
Propose changes to this page
Designed and developed bySpree Commerce & Ruby on Rails developers© Spree Commerce. 2021 All Rights Reserved.