Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Introducing `Spree::Category` (#13757)

Damian Legawiece52bf05bf9d3
diff --git a/docs/api-reference/store-api/localization.mdx b/docs/api-reference/store-api/localization.mdx
index c12a98c441..d025632c88 100644
--- a/docs/api-reference/store-api/localization.mdx
+++ b/docs/api-reference/store-api/localization.mdx
@@ -138,7 +138,7 @@ The locale and currency must be supported by the current store. If an unsupporte
## Translated Content
-When a locale is set, all translatable fields are returned in the requested language. This includes product names, descriptions, taxon names, and other content managed through [translations](/developer/core-concepts/translations).
+When a locale is set, all translatable fields are returned in the requested language. This includes product names, descriptions, category names, and other content managed through [translations](/developer/core-concepts/translations).
<CodeGroup>
diff --git a/docs/api-reference/store-api/querying.mdx b/docs/api-reference/store-api/querying.mdx
index d9a17474e6..47723ee3a3 100644
--- a/docs/api-reference/store-api/querying.mdx
+++ b/docs/api-reference/store-api/querying.mdx
@@ -87,25 +87,25 @@ You can filter by associated model attributes using underscore notation:
<CodeGroup>
```typescript SDK
-// Products in a specific taxon (category)
+// Products in a specific category
const products = await client.products.list({
- taxons_id_eq: 'txn_abc123',
+ categories_id_eq: 'ctg_abc123',
})
-// Taxons at a specific depth
-const taxons = await client.taxons.list({
+// Categories at a specific depth
+const categories = await client.categories.list({
depth_eq: 1,
})
```
```bash cURL
-# Products in a specific taxon
+# Products in a specific category
curl -G 'http://localhost:3000/api/v3/store/products' \
-H 'X-Spree-Api-Key: spree_pk_xxx' \
- --data-urlencode 'q[taxons_id_eq]=txn_abc123'
+ --data-urlencode 'q[categories_id_eq]=ctg_abc123'
-# Top-level taxons only
-curl -G 'http://localhost:3000/api/v3/store/taxons' \
+# Top-level categories only
+curl -G 'http://localhost:3000/api/v3/store/categories' \
-H 'X-Spree-Api-Key: spree_pk_xxx' \
--data-urlencode 'q[depth_eq]=1'
```
@@ -205,8 +205,8 @@ The `sort` parameter works on all list endpoints. Use any sortable column name:
<CodeGroup>
```typescript SDK
-// Taxons sorted by name
-const taxons = await client.taxons.list({
+// Categories sorted by name
+const categories = await client.categories.list({
sort: 'name',
})
@@ -214,16 +214,11 @@ const taxons = await client.taxons.list({
const orders = await client.customer.orders.list({
sort: '-completed_at',
})
-
-// Taxonomies sorted by name descending
-const taxonomies = await client.taxonomies.list({
- sort: '-name',
-})
```
```bash cURL
-# Taxons sorted by name
-curl -G 'http://localhost:3000/api/v3/store/taxons' \
+# Categories sorted by name
+curl -G 'http://localhost:3000/api/v3/store/categories' \
-H 'X-Spree-Api-Key: spree_pk_xxx' \
-d 'sort=name'
@@ -273,8 +268,8 @@ const product = await client.products.get('spree-tote', {
expand: ['variants.images', 'variants.metafields', 'option_types'],
})
-// Taxon with nested children
-const taxon = await client.taxons.get('categories/clothing', {
+// Category with nested children
+const category = await client.categories.get('clothing/shirts', {
expand: ['children.children'], // Two levels of subcategories
})
```
diff --git a/docs/api-reference/store-api/relations.mdx b/docs/api-reference/store-api/relations.mdx
index e4b2ec3ab8..b3d6007c80 100644
--- a/docs/api-reference/store-api/relations.mdx
+++ b/docs/api-reference/store-api/relations.mdx
@@ -84,7 +84,7 @@ With `?expand=variants,images`, the related resources are embedded:
| `master_variant` | The master variant |
| `images` | All product images (across all variants) |
| `option_types` | Option types (e.g., Size, Color) |
-| `taxons` | Categories this product belongs to |
+| `categories` | Categories this product belongs to |
| `metafields` | Public metafields (custom structured data) |
<CodeGroup>
@@ -103,37 +103,30 @@ curl -G 'http://localhost:3000/api/v3/store/products/spree-tote' \
</CodeGroup>
-### Taxons (Categories)
+### Categories
| Relation | Description |
|----------|-------------|
-| `ancestors` | Parent taxons (for breadcrumbs) |
-| `children` | Direct child taxons |
-| `products` | Products in this taxon |
+| `ancestors` | Parent categories (for breadcrumbs) |
+| `children` | Direct child categories |
+| `products` | Products in this category |
<CodeGroup>
```typescript SDK
-const taxon = await client.taxons.get('categories/clothing', {
+const category = await client.categories.get('clothing/shirts', {
expand: ['ancestors', 'children'],
})
```
```bash cURL
-curl -G 'http://localhost:3000/api/v3/store/taxons/categories/clothing' \
+curl -G 'http://localhost:3000/api/v3/store/categories/clothing/shirts' \
-H 'X-Spree-Api-Key: spree_pk_xxx' \
-d 'expand=ancestors,children'
```
</CodeGroup>
-### Taxonomies
-
-| Relation | Description |
-|----------|-------------|
-| `root` | Root taxon |
-| `taxons` | All taxons in this taxonomy |
-
### Countries
| Relation | Description |
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 6270b8aee7..2b0e8df5bb 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -661,16 +661,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImYxZDJjNzA3LTExMjYtNDhlYS04MGVmLTM0MjRjNjQyZjY5YyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMTQ3Mjg1fQ.RdWw8uBhScsYNXzwC9ipKZQD4nk4v-WHl8W6WfHSG9Y
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjZmNGNhMTM5LTU4OTktNGQ5NC1iMjU2LTkxNDMxZWMyMjg5MyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMTY1ODQ1fQ.arE64PcBNn_bqvkn3mNeprNTiYZGTxrhTsHs5aBt3ZA
user:
id: cus_UkLWZg9DAJ
- first_name: Ossie
- last_name: Little
+ first_name: Marlon
+ last_name: West
phone:
accepts_email_marketing: false
- created_at: '2026-03-10T11:54:45.396Z'
- updated_at: '2026-03-10T11:54:45.396Z'
+ created_at: '2026-03-10T17:04:05.201Z'
+ updated_at: '2026-03-10T17:04:05.201Z'
addresses: []
default_billing_address:
default_shipping_address:
@@ -747,16 +747,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6Ijc1NTc5ZTk4LTBmMDEtNDMyMC05YjZjLTA0ODkzMjA3NWRlNiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMTQ3Mjg2fQ.6UrBVbYJN-iR7MhNJKdpsNq1TtdROKJ8IM4cYX9ETWQ
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjdmOTNlMDgxLTk4MWItNGJiZi05NzNmLWY0ZWIwNTZmYTE0MCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMTY1ODQ2fQ.b6N44Rfgd1i1jNe-hcbkD70cqfX416s-mORw-l7Z4nQ
user:
id: cus_UkLWZg9DAJ
- first_name: Alishia
- last_name: Spinka
+ first_name: Scot
+ last_name: Emmerich
phone:
accepts_email_marketing: false
- created_at: '2026-03-10T11:54:46.767Z'
- updated_at: '2026-03-10T11:54:46.767Z'
+ created_at: '2026-03-10T17:04:06.613Z'
+ updated_at: '2026-03-10T17:04:06.613Z'
addresses: []
default_billing_address:
default_shipping_address:
@@ -828,13 +828,13 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R870266819
+ number: R566603277
state: cart
checkout_steps:
- address
- delivery
- complete
- token: 6oyG2GE9NkVvrg_oial1Zg1773143687532
+ token: Vbi67ooEnj4QRpELdX71hg1773162247402
email:
special_instructions:
currency: USD
@@ -860,8 +860,8 @@ paths:
total: '0.0'
display_total: "$0.00"
completed_at:
- created_at: '2026-03-10T11:54:47.533Z'
- updated_at: '2026-03-10T11:54:47.533Z'
+ created_at: '2026-03-10T17:04:07.404Z'
+ updated_at: '2026-03-10T17:04:07.404Z'
order_promotions: []
line_items: []
shipments: []
@@ -987,15 +987,15 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R340727030
+ number: R611627103
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: 28aYVK8uFS6ZNj8cVXdDGeCUdQtwhB534BZ
+ token: zqH8pYZ6ZtpmeJuamYMsjqNyq2XJzDxQwiy
special_instructions:
currency: USD
locale: en
@@ -1020,16 +1020,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-10T11:54:48.515Z'
- updated_at: '2026-03-10T11:54:48.563Z'
+ created_at: '2026-03-10T17:04:08.407Z'
+ updated_at: '2026-03-10T17:04:08.468Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 3856
- slug: product-3856
+ name: Product 39126
+ slug: product-39126
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1048,23 +1048,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:54:48.543Z'
- updated_at: '2026-03-10T11:54:48.543Z'
+ created_at: '2026-03-10T17:04:08.442Z'
+ updated_at: '2026-03-10T17:04:08.442Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H41088938114
+ number: H10115076175
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-10T11:54:48.548Z'
- updated_at: '2026-03-10T11:54:48.561Z'
+ created_at: '2026-03-10T17:04:08.449Z'
+ updated_at: '2026-03-10T17:04:08.466Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -1072,7 +1072,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_42
- name: Ruthie Konopelski
+ name: Aubrey Bruen
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1190,15 +1190,15 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R778027106
+ number: R676232166
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: uUYCVUCHiDbRD7DAENRsCQANdyzjwwajDVt
+ token: Adxhhn1GWaDXbesk6hwNRfHHgELLdY4pozi
special_instructions:
currency: USD
locale: en
@@ -1223,16 +1223,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-10T11:54:49.191Z'
- updated_at: '2026-03-10T11:54:49.247Z'
+ created_at: '2026-03-10T17:04:09.049Z'
+ updated_at: '2026-03-10T17:04:09.107Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 46277
- slug: product-46277
+ name: Product 45192
+ slug: product-45192
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1251,23 +1251,23 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:54:49.226Z'
- updated_at: '2026-03-10T11:54:49.226Z'
+ created_at: '2026-03-10T17:04:09.083Z'
+ updated_at: '2026-03-10T17:04:09.083Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H62768016531
+ number: H03365039999
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-10T11:54:49.231Z'
- updated_at: '2026-03-10T11:54:49.245Z'
+ created_at: '2026-03-10T17:04:09.089Z'
+ updated_at: '2026-03-10T17:04:09.104Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
@@ -1275,7 +1275,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: STATE_ABBR_46
- name: Hsiu Rippin
+ name: Elinore Mertz
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1351,15 +1351,14 @@ paths:
message: Order not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/countries":
+ "/api/v3/store/categories":
get:
- summary: List countries
+ summary: List categories
tags:
- - Internationalization
+ - Product Catalog
security:
- api_key: []
- description: Returns countries available in the store. Use ?expand=market to
- include market details (currency, locale, tax_inclusive).
+ description: Returns a paginated list of categories for the current store
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1371,13 +1370,32 @@ paths:
publishableKey: '<api-key>',
})
- const countries = await client.countries.list()
+ const categories = await client.categories.list({
+ page: 1,
+ limit: 25,
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
+ - name: page
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: q[name_cont]
+ in: query
+ required: false
+ description: Filter by name
+ schema:
+ type: string
- name: fields
in: query
required: false
@@ -1387,30 +1405,87 @@ paths:
type: string
responses:
'200':
- description: countries found
+ description: categories found
content:
application/json:
example:
data:
- - iso: DE
- iso3: IS19
- name: Germany
- states_required: false
- zipcode_required: true
- - iso: US
- iso3: USA
- name: United States of America
- states_required: true
- zipcode_required: true
+ - id: ctg_UkLWZg9DAJ
+ name: taxonomy_1
+ permalink: taxonomy-1
+ position: 0
+ depth: 0
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 1
+ created_at: '2026-03-10T17:04:11.284Z'
+ updated_at: '2026-03-10T17:04:11.338Z'
+ parent_id:
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: true
+ is_child: false
+ is_leaf: false
+ - id: ctg_gbHJdmfrXB
+ name: taxon_1
+ permalink: taxonomy-1/taxon-1
+ position: 0
+ depth: 1
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 1
+ created_at: '2026-03-10T17:04:11.291Z'
+ updated_at: '2026-03-10T17:04:11.338Z'
+ parent_id: ctg_UkLWZg9DAJ
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: false
+ is_child: true
+ is_leaf: false
+ - id: ctg_EfhxLZ9ck8
+ name: taxon_2
+ permalink: taxonomy-1/taxon-1/taxon-2
+ position: 0
+ depth: 2
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 0
+ created_at: '2026-03-10T17:04:11.301Z'
+ updated_at: '2026-03-10T17:04:11.307Z'
+ parent_id: ctg_gbHJdmfrXB
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: false
+ is_child: true
+ is_leaf: true
+ meta:
+ page: 1
+ limit: 25
+ count: 3
+ pages: 1
+ from: 1
+ to: 3
+ in: 3
+ previous:
+ next:
schema:
type: object
properties:
data:
type: array
items:
- "$ref": "#/components/schemas/Country"
- required:
- - data
+ "$ref": "#/components/schemas/Category"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
'401':
description: unauthorized
content:
@@ -1421,15 +1496,14 @@ paths:
message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/countries/{iso}":
+ "/api/v3/store/categories/{id}":
get:
- summary: Get a country
+ summary: Get a category
tags:
- - Internationalization
+ - Product Catalog
security:
- api_key: []
- description: Returns a single country by ISO code. Supports ?expand=states for
- address forms and ?expand=market for market details.
+ description: Returns a single category by permalink or prefix ID
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1441,17 +1515,26 @@ paths:
publishableKey: '<api-key>',
})
- const country = await client.countries.get('US')
+ const category = await client.categories.get('categories/clothing/shirts', {
+ expand: 'children',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: iso
+ - name: id
in: path
required: true
- description: Country ISO 3166-1 alpha-2 code (e.g., "US", "DE")
+ description: Category permalink (e.g., clothing/shirts) or prefix ID (e.g.,
+ ctg_abc123)
+ schema:
+ type: string
+ - name: expand
+ in: query
+ required: false
+ description: Expand associations (children, parent, ancestors, metafields)
schema:
type: string
- name: fields
@@ -1463,55 +1546,60 @@ paths:
type: string
responses:
'200':
- description: country found
+ description: category found by prefix ID
content:
application/json:
example:
- iso: US
- iso3: USA
- name: United States of America
- states_required: true
- zipcode_required: true
+ id: ctg_gbHJdmfrXB
+ name: taxon_10
+ permalink: taxonomy-7/taxon-10
+ position: 0
+ depth: 1
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 1
+ created_at: '2026-03-10T17:04:11.717Z'
+ updated_at: '2026-03-10T17:04:11.782Z'
+ parent_id: ctg_UkLWZg9DAJ
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: false
+ is_child: true
+ is_leaf: false
schema:
- type: object
- properties:
- iso:
- type: string
- iso3:
- type: string
- name:
- type: string
- states_required:
- type: boolean
- zipcode_required:
- type: boolean
- required:
- - iso
- - iso3
- - name
- - states_required
- - zipcode_required
+ "$ref": "#/components/schemas/Category"
'404':
- description: country not found
+ description: category from other store not accessible
content:
application/json:
example:
error:
code: record_not_found
- message: Country not found
+ message: Category not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/orders/{order_id}/coupon_codes":
- post:
- summary: Apply coupon code
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/categories/{category_id}/products":
+ get:
+ summary: List products in a category
tags:
- - Cart
+ - Product Catalog
security:
- api_key: []
- bearer_auth: []
- description: |
- Applies a coupon code to the order. Supports both promotion coupon codes and gift card codes.
- The code is matched case-insensitively.
+ description: Returns a paginated list of products belonging to the specified
+ category
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1523,8 +1611,11 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.couponCodes.apply('or_abc123', 'SAVE10', {
- bearerToken: '<token>',
+ const products = await client.categories.products.list('categories/clothing', {
+ page: 1,
+ limit: 25,
+ sort: 'price',
+ with_option_value_ids: ['optval_abc'],
})
parameters:
- name: x-spree-api-key
@@ -1532,253 +1623,148 @@ paths:
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: false
- description: Bearer token for authenticated customers
- schema:
- type: string
- - name: order_id
+ - name: category_id
in: path
required: true
- description: Order ID
+ description: Category permalink or prefix ID
schema:
type: string
- - name: x-spree-order-token
- in: header
+ - name: page
+ in: query
required: false
- description: Order token for guest access
+ description: 'Page number (default: 1)'
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: 'Number of items per page (default: 25, max: 100)'
+ schema:
+ type: integer
+ - name: sort
+ in: query
+ required: false
+ description: 'Sort order. Prefix with - for descending. Values: price, -price,
+ best_selling, name, -name, -available_on, available_on'
schema:
type: string
- - name: Idempotency-Key
- in: header
+ - name: q[price_gte]
+ in: query
required: false
- description: Unique key for request idempotency. Duplicate requests with the
- same key return the cached response.
+ description: Filter by minimum price
+ schema:
+ type: number
+ - name: q[price_lte]
+ in: query
+ required: false
+ description: Filter by maximum price
+ schema:
+ type: number
+ - name: q[with_option_value_ids][]
+ in: query
+ required: false
+ description: Filter by option value prefix IDs
+ schema:
+ type: string
+ - name: q[in_stock]
+ in: query
+ required: false
+ description: Filter to only in-stock products
+ schema:
+ type: boolean
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
- '201':
- description: coupon code applied (gift card)
+ '200':
+ description: products found
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R609885086
- state: cart
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: d3Rd8KRAtdhPdvmDZsM6XmzBLfs7J73HCEe
- special_instructions:
- currency: USD
- locale: en
- item_count: 1
- state_lock_version: 1
- shipment_state:
- payment_state:
- item_total: '10.0'
- display_item_total: "$10.00"
- ship_total: '100.0'
- display_ship_total: "$100.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- completed_at:
- created_at: '2026-03-10T11:54:52.794Z'
- updated_at: '2026-03-10T11:54:52.912Z'
- order_promotions: []
- line_items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- currency: USD
- name: Product 94723
- slug: product-94723
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:54:52.823Z'
- updated_at: '2026-03-10T11:54:52.823Z'
- compare_at_amount:
+ data:
+ - id: prod_UkLWZg9DAJ
+ name: Product 156044
+ description: |-
+ At tempora iure expedita quae magnam consectetur beatae. Repudiandae repellat assumenda vitae laudantium officia. Minima eos placeat ipsa laborum.
+ Mollitia quo numquam quisquam qui cumque illo quis. Numquam sed pariatur incidunt laborum fugiat rerum maiores temporibus. Error facere cum excepturi similique accusamus quis in at. Aspernatur ducimus ipsa eligendi hic voluptatem magnam. Dolorum laborum ea necessitatibus eius amet.
+ Nesciunt quo blanditiis veniam animi officia vero. Excepturi nobis corrupti ad error rem accusantium exercitationem. Veniam harum recusandae ipsa nostrum nihil. Quasi dolorum praesentium doloremque illo sed. Harum id enim dicta voluptatem deleniti ex.
+ slug: product-156044
+ meta_description:
+ meta_keywords:
+ variant_count: 0
+ available_on: '2025-03-10T17:04:12.315Z'
+ created_at: '2026-03-10T17:04:12.330Z'
+ updated_at: '2026-03-10T17:04:12.342Z'
+ purchasable: true
+ in_stock: false
+ backorderable: true
+ available: true
+ default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
- option_values: []
- digital_links: []
- shipments:
- - id: ship_UkLWZg9DAJ
- number: H97551178451
- state: pending
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- shipped_at:
- created_at: '2026-03-10T11:54:52.829Z'
- updated_at: '2026-03-10T11:54:52.842Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_66
- name: Garnett Bogan
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_66
- shipping_rates:
- - id: shpr_UkLWZg9DAJ
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '100.0'
- display_cost: "$100.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- payments:
- - id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- state: checkout
- response_code: 1-SC-20260310115452901014
- number: PXTTYFJ3
- amount: '50.0'
- display_amount: "$50.00"
- created_at: '2026-03-10T11:54:52.905Z'
- updated_at: '2026-03-10T11:54:52.905Z'
- source_type: store_credit
- source_id: credit_UkLWZg9DAJ
- source:
- id: credit_UkLWZg9DAJ
- amount: '50.0'
- amount_used: '0.0'
- amount_remaining: '50.0'
- display_amount: "$50.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$50.00"
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
currency: USD
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Store Credit
- description:
- type: Spree::PaymentMethod::StoreCredit
- session_required: false
- bill_address:
- id: addr_EfhxLZ9ck8
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 67 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_68
- state_abbr: STATE_ABBR_68
- quick_checkout: false
- state_name: STATE_NAME_68
- ship_address:
- id: addr_VqXmZF31wY
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 68 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_69
- state_abbr: STATE_ABBR_69
- quick_checkout: false
- state_name: STATE_NAME_69
- payment_methods:
- - id: pm_UkLWZg9DAJ
- name: Store Credit
- description:
- type: Spree::PaymentMethod::StoreCredit
- session_required: false
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/Order"
- '422':
- description: invalid coupon code
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Product"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ '404':
+ description: category not found
content:
application/json:
example:
error:
- code: processing_error
- message: The coupon code you entered doesn't exist. Please try again.
+ code: record_not_found
+ message: Category not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- '404':
- description: order not found
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: order_not_found
- message: Couldn't find Spree::Order with 'id'=245546638656678833
- [WHERE "spree_orders"."store_id" = ? AND "spree_orders"."user_id"
- = ?]
+ code: invalid_token
+ message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- code:
- type: string
- example: SAVE10
- description: Coupon code or gift card code to apply
- required:
- - code
- "/api/v3/store/orders/{order_id}/coupon_codes/{id}":
- delete:
- summary: Remove coupon code
+ "/api/v3/store/countries":
+ get:
+ summary: List countries
tags:
- - Cart
+ - Internationalization
security:
- api_key: []
- bearer_auth: []
- description: Removes a previously applied coupon code from the order.
+ description: Returns countries available in the store. Use ?expand=market to
+ include market details (currency, locale, tax_inclusive).
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1790,67 +1776,220 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.couponCodes.remove('or_abc123', 'op_abc123', {
- bearerToken: '<token>',
- })
+ const countries = await client.countries.list()
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: false
- description: Bearer token for authenticated customers
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Order promotion ID
- schema:
- type: string
- - name: x-spree-order-token
- in: header
+ - name: fields
+ in: query
required: false
- description: Order token for guest access
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
'200':
- description: coupon code removed
+ description: countries found
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R454182979
- state: cart
- checkout_steps:
- - address
- - delivery
- - payment
- - complete
- token: UCaHVS7xLVZve6GS8zQs4MaHhNYzJBMJVEG
- special_instructions:
- currency: USD
- locale: en
- item_count: 1
- state_lock_version: 1
- shipment_state:
- payment_state:
- item_total: '10.0'
- display_item_total: "$10.00"
- ship_total: '100.0'
- display_ship_total: "$100.00"
- adjustment_total: '0.0'
+ data:
+ - iso: DE
+ iso3: IS19
+ name: Germany
+ states_required: false
+ zipcode_required: true
+ - iso: US
+ iso3: USA
+ name: United States of America
+ states_required: true
+ zipcode_required: true
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Country"
+ required:
+ - data
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/countries/{iso}":
+ get:
+ summary: Get a country
+ tags:
+ - Internationalization
+ security:
+ - api_key: []
+ description: Returns a single country by ISO code. Supports ?expand=states for
+ address forms and ?expand=market for market details.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const country = await client.countries.get('US')
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: iso
+ in: path
+ required: true
+ description: Country ISO 3166-1 alpha-2 code (e.g., "US", "DE")
+ schema:
+ type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
+ schema:
+ type: string
+ responses:
+ '200':
+ description: country found
+ content:
+ application/json:
+ example:
+ iso: US
+ iso3: USA
+ name: United States of America
+ states_required: true
+ zipcode_required: true
+ schema:
+ type: object
+ properties:
+ iso:
+ type: string
+ iso3:
+ type: string
+ name:
+ type: string
+ states_required:
+ type: boolean
+ zipcode_required:
+ type: boolean
+ required:
+ - iso
+ - iso3
+ - name
+ - states_required
+ - zipcode_required
+ '404':
+ description: country not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Country not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/orders/{order_id}/coupon_codes":
+ post:
+ summary: Apply coupon code
+ tags:
+ - Cart
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |
+ Applies a coupon code to the order. Supports both promotion coupon codes and gift card codes.
+ The code is matched case-insensitively.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const order = await client.orders.couponCodes.apply('or_abc123', 'SAVE10', {
+ bearerToken: '<token>',
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: false
+ description: Bearer token for authenticated customers
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: x-spree-order-token
+ in: header
+ required: false
+ description: Order token for guest access
+ schema:
+ type: string
+ - name: Idempotency-Key
+ in: header
+ required: false
+ description: Unique key for request idempotency. Duplicate requests with the
+ same key return the cached response.
+ schema:
+ type: string
+ responses:
+ '201':
+ description: coupon code applied (gift card)
+ content:
+ application/json:
+ example:
+ id: or_UkLWZg9DAJ
+ number: R099009108
+ state: cart
+ checkout_steps:
+ - address
+ - delivery
+ - payment
+ - complete
+ token: tagwKUrjm2YSpCHTdWRga92CHnhMPi1mEK8
+ special_instructions:
+ currency: USD
+ locale: en
+ item_count: 1
+ state_lock_version: 1
+ shipment_state:
+ payment_state:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ ship_total: '100.0'
+ display_ship_total: "$100.00"
+ adjustment_total: '0.0'
display_adjustment_total: "$0.00"
promo_total: '0.0'
display_promo_total: "$0.00"
@@ -1863,16 +2002,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-10T11:54:54.678Z'
- updated_at: '2026-03-10T11:54:54.776Z'
+ created_at: '2026-03-10T17:04:14.179Z'
+ updated_at: '2026-03-10T17:04:14.290Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 121410
- slug: product-121410
+ name: Product 198696
+ slug: product-198696
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1891,37 +2030,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:54:54.706Z'
- updated_at: '2026-03-10T11:54:54.772Z'
+ created_at: '2026-03-10T17:04:14.215Z'
+ updated_at: '2026-03-10T17:04:14.215Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H39652636415
+ number: H32397292586
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-10T11:54:54.711Z'
- updated_at: '2026-03-10T11:54:54.722Z'
+ created_at: '2026-03-10T17:04:14.221Z'
+ updated_at: '2026-03-10T17:04:14.234Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_78
- name: Armandina O'Conner
+ state_abbr: STATE_ABBR_76
+ name: Hilda Jerde
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_78
+ state_text: STATE_ABBR_76
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -1933,13 +2072,39 @@ paths:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
- payments: []
+ payments:
+ - id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ state: checkout
+ response_code: 1-SC-20260310170414280732
+ number: PECNCT6N
+ amount: '50.0'
+ display_amount: "$50.00"
+ created_at: '2026-03-10T17:04:14.284Z'
+ updated_at: '2026-03-10T17:04:14.284Z'
+ source_type: store_credit
+ source_id: credit_UkLWZg9DAJ
+ source:
+ id: credit_UkLWZg9DAJ
+ amount: '50.0'
+ amount_used: '0.0'
+ amount_remaining: '50.0'
+ display_amount: "$50.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$50.00"
+ currency: USD
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Store Credit
+ description:
+ type: Spree::PaymentMethod::StoreCredit
+ session_required: false
bill_address:
id: addr_EfhxLZ9ck8
firstname: John
lastname: Doe
full_name: John Doe
- address1: 79 Lovely Street
+ address1: 67 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -1947,16 +2112,16 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_80
- state_abbr: STATE_ABBR_80
+ state_text: STATE_ABBR_78
+ state_abbr: STATE_ABBR_78
quick_checkout: false
- state_name: STATE_NAME_80
+ state_name: STATE_NAME_78
ship_address:
id: addr_VqXmZF31wY
firstname: John
lastname: Doe
full_name: John Doe
- address1: 80 Lovely Street
+ address1: 68 Lovely Street
address2: Northwest
city: Herndon
zipcode: '35005'
@@ -1964,35 +2129,275 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_81
- state_abbr: STATE_ABBR_81
+ state_text: STATE_ABBR_79
+ state_abbr: STATE_ABBR_79
quick_checkout: false
- state_name: STATE_NAME_81
- payment_methods: []
+ state_name: STATE_NAME_79
+ payment_methods:
+ - id: pm_UkLWZg9DAJ
+ name: Store Credit
+ description:
+ type: Spree::PaymentMethod::StoreCredit
+ session_required: false
schema:
"$ref": "#/components/schemas/Order"
+ '422':
+ description: invalid coupon code
+ content:
+ application/json:
+ example:
+ error:
+ code: processing_error
+ message: The coupon code you entered doesn't exist. Please try again.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
'404':
- description: coupon code not found on order
+ description: order not found
content:
application/json:
example:
error:
- code: record_not_found
- message: Couldn't find Spree::OrderPromotion with 'id'=245546638656678833
- [WHERE "spree_order_promotions"."order_id" = ?]
+ code: order_not_found
+ message: Couldn't find Spree::Order with 'id'=245546638656678833
+ [WHERE "spree_orders"."store_id" = ? AND "spree_orders"."user_id"
+ = ?]
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customer/credit_cards":
- get:
- summary: List saved credit cards
- tags:
- - Customers
- security:
- - api_key: []
- bearer_auth: []
- description: Returns all saved credit cards for the authenticated customer
- x-codeSamples:
- - lang: javascript
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ code:
+ type: string
+ example: SAVE10
+ description: Coupon code or gift card code to apply
+ required:
+ - code
+ "/api/v3/store/orders/{order_id}/coupon_codes/{id}":
+ delete:
+ summary: Remove coupon code
+ tags:
+ - Cart
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Removes a previously applied coupon code from the order.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const order = await client.orders.couponCodes.remove('or_abc123', 'op_abc123', {
+ bearerToken: '<token>',
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: false
+ description: Bearer token for authenticated customers
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Order promotion ID
+ schema:
+ type: string
+ - name: x-spree-order-token
+ in: header
+ required: false
+ description: Order token for guest access
+ schema:
+ type: string
+ responses:
+ '200':
+ description: coupon code removed
+ content:
+ application/json:
+ example:
+ id: or_UkLWZg9DAJ
+ number: R062686836
+ state: cart
+ checkout_steps:
+ - address
+ - delivery
+ - payment
+ - complete
+ token: EZpVTuMvjWumkYFitNFQkemRz2qxYSidDUm
+ special_instructions:
+ currency: USD
+ locale: en
+ item_count: 1
+ state_lock_version: 1
+ shipment_state:
+ payment_state:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ ship_total: '100.0'
+ display_ship_total: "$100.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ completed_at:
+ created_at: '2026-03-10T17:04:16.057Z'
+ updated_at: '2026-03-10T17:04:16.181Z'
+ order_promotions: []
+ line_items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ currency: USD
+ name: Product 226425
+ slug: product-226425
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ promo_total: '0.0'
+ display_promo_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-10T17:04:16.087Z'
+ updated_at: '2026-03-10T17:04:16.176Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ shipments:
+ - id: ship_UkLWZg9DAJ
+ number: H30874485277
+ state: pending
+ tracking: U10000
+ tracking_url:
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipped_at:
+ created_at: '2026-03-10T17:04:16.092Z'
+ updated_at: '2026-03-10T17:04:16.106Z'
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_88
+ name: Petra Langosh
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_88
+ shipping_rates:
+ - id: shpr_UkLWZg9DAJ
+ shipping_method_id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ payments: []
+ bill_address:
+ id: addr_EfhxLZ9ck8
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 79 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_90
+ state_abbr: STATE_ABBR_90
+ quick_checkout: false
+ state_name: STATE_NAME_90
+ ship_address:
+ id: addr_VqXmZF31wY
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 80 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_91
+ state_abbr: STATE_ABBR_91
+ quick_checkout: false
+ state_name: STATE_NAME_91
+ payment_methods: []
+ schema:
+ "$ref": "#/components/schemas/Order"
+ '404':
+ description: coupon code not found on order
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Couldn't find Spree::OrderPromotion with 'id'=245546638656678833
+ [WHERE "spree_order_promotions"."order_id" = ?]
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/customer/credit_cards":
+ get:
+ summary: List saved credit cards
+ tags:
+ - Customers
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Returns all saved credit cards for the authenticated customer
+ x-codeSamples:
+ - lang: javascript
label: Spree SDK
source: |-
import { createClient } from '@spree/sdk'
@@ -2345,15 +2750,15 @@ paths:
example:
data:
- id: or_UkLWZg9DAJ
- number: R900102056
+ number: R350199218
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: hbs1Uthj2fAFpH98TXYrJBGkkQUkUDRReXG
+ token: qeyhApjW9bSEvShvbcGCkMstn48q1M73N9T
special_instructions:
currency: USD
locale: en
@@ -2378,16 +2783,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-10T11:54:59.364Z'
- updated_at: '2026-03-10T11:54:59.427Z'
+ created_at: '2026-03-10T17:04:20.838Z'
+ updated_at: '2026-03-10T17:04:20.911Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 146979
- slug: product-146979
+ name: Product 244861
+ slug: product-244861
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2406,37 +2811,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:54:59.405Z'
- updated_at: '2026-03-10T11:54:59.405Z'
+ created_at: '2026-03-10T17:04:20.885Z'
+ updated_at: '2026-03-10T17:04:20.885Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H02388731602
+ number: H25589098875
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-10T11:54:59.410Z'
- updated_at: '2026-03-10T11:54:59.425Z'
+ created_at: '2026-03-10T17:04:20.891Z'
+ updated_at: '2026-03-10T17:04:20.908Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_100
- name: Alicia Luettgen
+ state_abbr: STATE_ABBR_108
+ name: Monet Doyle
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_100
+ state_text: STATE_ABBR_108
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -2462,10 +2867,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_100
- state_abbr: STATE_ABBR_100
+ state_text: STATE_ABBR_110
+ state_abbr: STATE_ABBR_110
quick_checkout: false
- state_name: STATE_NAME_100
+ state_name: STATE_NAME_110
ship_address:
id: addr_VqXmZF31wY
firstname: John
@@ -2479,10 +2884,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_101
- state_abbr: STATE_ABBR_101
+ state_text: STATE_ABBR_111
+ state_abbr: STATE_ABBR_111
quick_checkout: false
- state_name: STATE_NAME_101
+ state_name: STATE_NAME_111
payment_methods: []
meta:
page: 1
@@ -2554,7 +2959,7 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImYxZmIyNTEyLTA4ODctNDMzYi1iZGQ2LWQ0ZjIxNzdkZWU2MSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMTQ3MzAwfQ.3bXljTu_S0BpTU8Sf6Oz7mEpCNYqgyU1ylL5rA_SOAs
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjVkOWNhMjM2LTEwZTEtNDczMC04YmNiLTBkMTgwZDg1MGFjMSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzczMTY1ODYxfQ.-rzaJDSb7_KpPTpgiiFaCr80Zr8JY-YTxlq4lrOCT7s
user:
id: cus_UkLWZg9DAJ
@@ -2562,8 +2967,8 @@ paths:
last_name: Doe
phone: "+1234567890"
accepts_email_marketing: true
- created_at: '2026-03-10T11:55:00.322Z'
- updated_at: '2026-03-10T11:55:00.322Z'
+ created_at: '2026-03-10T17:04:21.838Z'
+ updated_at: '2026-03-10T17:04:21.838Z'
addresses: []
default_billing_address:
default_shipping_address:
@@ -2667,13 +3072,13 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
- first_name: Shakita
- last_name: Jenkins
+ first_name: Otelia
+ last_name: Witting
phone: 555-555-0199
accepts_email_marketing: false
- created_at: '2026-03-10T11:55:00.878Z'
- updated_at: '2026-03-10T11:55:01.146Z'
+ created_at: '2026-03-10T17:04:22.391Z'
+ updated_at: '2026-03-10T17:04:22.676Z'
addresses:
- id: addr_gbHJdmfrXB
firstname: John
@@ -2687,10 +3092,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_107
- state_abbr: STATE_ABBR_107
+ state_text: STATE_ABBR_117
+ state_abbr: STATE_ABBR_117
quick_checkout: false
- state_name: STATE_NAME_107
+ state_name: STATE_NAME_117
- id: addr_UkLWZg9DAJ
firstname: John
lastname: Doe
@@ -2703,10 +3108,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_106
- state_abbr: STATE_ABBR_106
+ state_text: STATE_ABBR_116
+ state_abbr: STATE_ABBR_116
quick_checkout: false
- state_name: STATE_NAME_106
+ state_name: STATE_NAME_116
default_billing_address:
id: addr_gbHJdmfrXB
firstname: John
@@ -2720,10 +3125,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_107
- state_abbr: STATE_ABBR_107
+ state_text: STATE_ABBR_117
+ state_abbr: STATE_ABBR_117
quick_checkout: false
- state_name: STATE_NAME_107
+ state_name: STATE_NAME_117
default_shipping_address:
id: addr_UkLWZg9DAJ
firstname: John
@@ -2737,10 +3142,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_106
- state_abbr: STATE_ABBR_106
+ state_text: STATE_ABBR_116
+ state_abbr: STATE_ABBR_116
quick_checkout: false
- state_name: STATE_NAME_106
+ state_name: STATE_NAME_116
schema:
"$ref": "#/components/schemas/Customer"
'401':
@@ -2797,13 +3202,13 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
first_name: Updated
last_name: Name
phone: 555-555-0199
accepts_email_marketing: false
- created_at: '2026-03-10T11:55:01.432Z'
- updated_at: '2026-03-10T11:55:01.709Z'
+ created_at: '2026-03-10T17:04:22.966Z'
+ updated_at: '2026-03-10T17:04:23.269Z'
addresses:
- id: addr_gbHJdmfrXB
firstname: John
@@ -2817,10 +3222,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_109
- state_abbr: STATE_ABBR_109
+ state_text: STATE_ABBR_119
+ state_abbr: STATE_ABBR_119
quick_checkout: false
- state_name: STATE_NAME_109
+ state_name: STATE_NAME_119
- id: addr_UkLWZg9DAJ
firstname: John
lastname: Doe
@@ -2833,10 +3238,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_108
- state_abbr: STATE_ABBR_108
+ state_text: STATE_ABBR_118
+ state_abbr: STATE_ABBR_118
quick_checkout: false
- state_name: STATE_NAME_108
+ state_name: STATE_NAME_118
default_billing_address:
id: addr_gbHJdmfrXB
firstname: John
@@ -2850,10 +3255,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_109
- state_abbr: STATE_ABBR_109
+ state_text: STATE_ABBR_119
+ state_abbr: STATE_ABBR_119
quick_checkout: false
- state_name: STATE_NAME_109
+ state_name: STATE_NAME_119
default_shipping_address:
id: addr_UkLWZg9DAJ
firstname: John
@@ -2867,10 +3272,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_108
- state_abbr: STATE_ABBR_108
+ state_text: STATE_ABBR_118
+ state_abbr: STATE_ABBR_118
quick_checkout: false
- state_name: STATE_NAME_108
+ state_name: STATE_NAME_118
schema:
"$ref": "#/components/schemas/Customer"
'422':
@@ -3027,7 +3432,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: 2B824A4F3A03008B
+ code: B808F5A9CEEB4C30
state: active
currency: USD
amount: '10.0'
@@ -3041,8 +3446,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-03-10T11:55:04.785Z'
- updated_at: '2026-03-10T11:55:04.785Z'
+ created_at: '2026-03-10T17:04:26.496Z'
+ updated_at: '2026-03-10T17:04:26.496Z'
meta:
page: 1
limit: 25
@@ -3125,7 +3530,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 2AAC58DB48A4E335
+ code: D6D1841288553AB1
state: active
currency: USD
amount: '10.0'
@@ -3139,8 +3544,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-03-10T11:55:05.905Z'
- updated_at: '2026-03-10T11:55:05.905Z'
+ created_at: '2026-03-10T17:04:27.590Z'
+ updated_at: '2026-03-10T17:04:27.590Z'
schema:
"$ref": "#/components/schemas/GiftCard"
'404':
@@ -3218,15 +3623,15 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R818973497
+ number: R910591887
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: 4D8ehUqKgbDqdrQ5u7DMyYg46c4p49Yr2a6
+ token: hX1Lt6FYjSvJEegD2k5YjsKrBntPRvnAavL
special_instructions:
currency: USD
locale: en
@@ -3251,16 +3656,16 @@ paths:
total: '29.99'
display_total: "$29.99"
completed_at:
- created_at: '2026-03-10T11:55:07.664Z'
- updated_at: '2026-03-10T11:55:07.760Z'
+ created_at: '2026-03-10T17:04:29.336Z'
+ updated_at: '2026-03-10T17:04:29.430Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 245107
- slug: product-245107
+ name: Product 344628
+ slug: product-344628
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3279,8 +3684,8 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:55:07.695Z'
- updated_at: '2026-03-10T11:55:07.695Z'
+ created_at: '2026-03-10T17:04:29.365Z'
+ updated_at: '2026-03-10T17:04:29.365Z'
compare_at_amount:
thumbnail_url:
option_values: []
@@ -3289,8 +3694,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 25268
- slug: product-25268
+ name: Product 353236
+ slug: product-353236
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -3309,8 +3714,8 @@ paths:
discounted_amount: '19.99'
display_discounted_amount: "$19.99"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:55:07.737Z'
- updated_at: '2026-03-10T11:55:07.737Z'
+ created_at: '2026-03-10T17:04:29.407Z'
+ updated_at: '2026-03-10T17:04:29.407Z'
compare_at_amount:
thumbnail_url:
option_values: []
@@ -3330,10 +3735,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_137
- state_abbr: STATE_ABBR_137
+ state_text: STATE_ABBR_147
+ state_abbr: STATE_ABBR_147
quick_checkout: false
- state_name: STATE_NAME_137
+ state_name: STATE_NAME_147
ship_address:
payment_methods: []
schema:
@@ -3430,14 +3835,14 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R766986597
+ number: R791655168
state: cart
checkout_steps:
- address
- delivery
- complete
- token: W1ko5BzSeoH3MUvwqATs1yi78LarHPYGZwx
+ token: nMy9E556iyogVQNDRPmuywUtbMzDURtkKTy
special_instructions:
currency: USD
locale: en
@@ -3462,16 +3867,16 @@ paths:
total: '0.0'
display_total: "$0.00"
completed_at:
- created_at: '2026-03-10T11:55:10.090Z'
- updated_at: '2026-03-10T11:55:10.125Z'
+ created_at: '2026-03-10T17:04:31.802Z'
+ updated_at: '2026-03-10T17:04:31.834Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 297273
- slug: product-297273
+ name: Product 391152
+ slug: product-391152
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3490,8 +3895,8 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:55:10.124Z'
- updated_at: '2026-03-10T11:55:10.143Z'
+ created_at: '2026-03-10T17:04:31.833Z'
+ updated_at: '2026-03-10T17:04:31.851Z'
compare_at_amount:
thumbnail_url:
option_values: []
@@ -3511,10 +3916,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_149
- state_abbr: STATE_ABBR_149
+ state_text: STATE_ABBR_159
+ state_abbr: STATE_ABBR_159
quick_checkout: false
- state_name: STATE_NAME_149
+ state_name: STATE_NAME_159
ship_address:
payment_methods: []
schema:
@@ -3590,14 +3995,14 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R214035235
+ number: R584020025
state: cart
checkout_steps:
- address
- delivery
- complete
- token: euuy4646qJw6W1LiQfCytf1DKVi8Yu7EDyx
+ token: fDabjRHTJTgCfnXRsW7pixnuRuCZzh4kS72
special_instructions:
currency: USD
locale: en
@@ -3622,8 +4027,8 @@ paths:
total: '0.0'
display_total: "$0.00"
completed_at:
- created_at: '2026-03-10T11:55:10.687Z'
- updated_at: '2026-03-10T11:55:10.736Z'
+ created_at: '2026-03-10T17:04:32.439Z'
+ updated_at: '2026-03-10T17:04:32.504Z'
order_promotions: []
line_items: []
shipments: []
@@ -3641,10 +4046,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_152
- state_abbr: STATE_ABBR_152
+ state_text: STATE_ABBR_162
+ state_abbr: STATE_ABBR_162
quick_checkout: false
- state_name: STATE_NAME_152
+ state_name: STATE_NAME_162
ship_address:
payment_methods: []
schema:
@@ -4179,14 +4584,14 @@ paths:
application/json:
example:
id: or_gbHJdmfrXB
- number: R809158598
+ number: R805209960
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: WmG3fhdiTqW6BVS1ztVhvgduuowJRbw7mQG
+ token: hY2ic7vcmDnqZCwum3x5i9UwAWghGR6JwBC
email:
special_instructions:
currency: USD
@@ -4212,16 +4617,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-10T11:55:13.014Z'
- updated_at: '2026-03-10T11:55:13.055Z'
+ created_at: '2026-03-10T17:04:34.973Z'
+ updated_at: '2026-03-10T17:04:35.018Z'
order_promotions: []
line_items:
- id: li_gbHJdmfrXB
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 348947
- slug: product-348947
+ name: Product 444781
+ slug: product-444781
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4240,37 +4645,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:55:13.038Z'
- updated_at: '2026-03-10T11:55:13.038Z'
+ created_at: '2026-03-10T17:04:35.000Z'
+ updated_at: '2026-03-10T17:04:35.000Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_gbHJdmfrXB
- number: H48050932426
+ number: H75004939866
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-10T11:55:13.044Z'
- updated_at: '2026-03-10T11:55:13.053Z'
+ created_at: '2026-03-10T17:04:35.007Z'
+ updated_at: '2026-03-10T17:04:35.016Z'
shipping_method:
id: shpm_gbHJdmfrXB
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_160
- name: Jamila Walsh
+ state_abbr: STATE_ABBR_170
+ name: Chung Tillman
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_160
+ state_text: STATE_ABBR_170
shipping_rates:
- id: shpr_gbHJdmfrXB
shipping_method_id: shpm_gbHJdmfrXB
@@ -4296,10 +4701,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_164
- state_abbr: STATE_ABBR_164
+ state_text: STATE_ABBR_174
+ state_abbr: STATE_ABBR_174
quick_checkout: false
- state_name: STATE_NAME_164
+ state_name: STATE_NAME_174
ship_address:
id: addr_OIJLhNcSbf
firstname: John
@@ -4313,10 +4718,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_165
- state_abbr: STATE_ABBR_165
+ state_text: STATE_ABBR_175
+ state_abbr: STATE_ABBR_175
quick_checkout: false
- state_name: STATE_NAME_165
+ state_name: STATE_NAME_175
payment_methods: []
schema:
"$ref": "#/components/schemas/Order"
@@ -4403,15 +4808,15 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R076447001
+ number: R200672713
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: RChwF94e97iR8bEwHzpb6zUPvwXkh92uH2T
+ token: 6A1ihueJxQfB2Et23r7SEyC15sU2v5LLcFw
special_instructions:
currency: USD
locale: en
@@ -4436,16 +4841,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-10T11:55:16.383Z'
- updated_at: '2026-03-10T11:55:16.445Z'
+ created_at: '2026-03-10T17:04:38.392Z'
+ updated_at: '2026-03-10T17:04:38.469Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 408589
- slug: product-408589
+ name: Product 502226
+ slug: product-502226
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4464,37 +4869,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:55:16.411Z'
- updated_at: '2026-03-10T11:55:16.411Z'
+ created_at: '2026-03-10T17:04:38.423Z'
+ updated_at: '2026-03-10T17:04:38.423Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H76796629919
+ number: H10876887956
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-10T11:55:16.416Z'
- updated_at: '2026-03-10T11:55:16.429Z'
+ created_at: '2026-03-10T17:04:38.428Z'
+ updated_at: '2026-03-10T17:04:38.442Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_183
- name: Genoveva Ratke
+ state_abbr: STATE_ABBR_193
+ name: Jerold McGlynn
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_183
+ state_text: STATE_ABBR_193
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -4520,10 +4925,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_185
- state_abbr: STATE_ABBR_185
+ state_text: STATE_ABBR_195
+ state_abbr: STATE_ABBR_195
quick_checkout: false
- state_name: STATE_NAME_185
+ state_name: STATE_NAME_195
ship_address:
id: addr_VqXmZF31wY
firstname: John
@@ -4537,10 +4942,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_186
- state_abbr: STATE_ABBR_186
+ state_text: STATE_ABBR_196
+ state_abbr: STATE_ABBR_196
quick_checkout: false
- state_name: STATE_NAME_186
+ state_name: STATE_NAME_196
payment_methods: []
schema:
"$ref": "#/components/schemas/Order"
@@ -4720,15 +5125,15 @@ paths:
application/json:
example:
id: or_gbHJdmfrXB
- number: R831787196
+ number: R308013991
state: address
checkout_steps:
- address
- delivery
- payment
- complete
- token: 6tkEm8JBEXWb9YPhxDUQzAdfr3t37r7BWPd
+ token: nz8S6B3ucvQP3mq9rsao8sSvQ719AizpeZa
special_instructions:
currency: USD
locale: en
@@ -4753,16 +5158,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-10T11:55:17.720Z'
- updated_at: '2026-03-10T11:55:17.784Z'
+ created_at: '2026-03-10T17:04:39.752Z'
+ updated_at: '2026-03-10T17:04:39.816Z'
order_promotions: []
line_items:
- id: li_gbHJdmfrXB
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 442673
- slug: product-442673
+ name: Product 546220
+ slug: product-546220
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4781,37 +5186,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:55:17.747Z'
- updated_at: '2026-03-10T11:55:17.747Z'
+ created_at: '2026-03-10T17:04:39.778Z'
+ updated_at: '2026-03-10T17:04:39.778Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_gbHJdmfrXB
- number: H77274941926
+ number: H37308014112
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-10T11:55:17.753Z'
- updated_at: '2026-03-10T11:55:17.763Z'
+ created_at: '2026-03-10T17:04:39.785Z'
+ updated_at: '2026-03-10T17:04:39.796Z'
shipping_method:
id: shpm_gbHJdmfrXB
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_193
- name: Kathey Shanahan
+ state_abbr: STATE_ABBR_203
+ name: Mika Wilderman
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_193
+ state_text: STATE_ABBR_203
shipping_rates:
- id: shpr_gbHJdmfrXB
shipping_method_id: shpm_gbHJdmfrXB
@@ -4837,10 +5242,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_197
- state_abbr: STATE_ABBR_197
+ state_text: STATE_ABBR_207
+ state_abbr: STATE_ABBR_207
quick_checkout: false
- state_name: STATE_NAME_197
+ state_name: STATE_NAME_207
ship_address:
id: addr_OIJLhNcSbf
firstname: John
@@ -4854,10 +5259,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_198
- state_abbr: STATE_ABBR_198
+ state_text: STATE_ABBR_208
+ state_abbr: STATE_ABBR_208
quick_checkout: false
- state_name: STATE_NAME_198
+ state_name: STATE_NAME_208
payment_methods: []
schema:
"$ref": "#/components/schemas/Order"
@@ -4930,15 +5335,15 @@ paths:
application/json:
example:
id: or_gbHJdmfrXB
- number: R737242485
+ number: R256036719
state: payment
checkout_steps:
- address
- delivery
- payment
- complete
- token: rYDiK6V35Awx2pojXc7WMbaGAxVCNEwuagV
+ token: Ke5TvpPLo2GPYwV5cvTDV8qVdkaYe4QZkc2
special_instructions:
currency: USD
locale: en
@@ -4963,16 +5368,16 @@ paths:
total: '29.99'
display_total: "$29.99"
completed_at:
- created_at: '2026-03-10T11:55:19.057Z'
- updated_at: '2026-03-10T11:55:19.246Z'
+ created_at: '2026-03-10T17:04:41.098Z'
+ updated_at: '2026-03-10T17:04:41.242Z'
order_promotions: []
line_items:
- id: li_gbHJdmfrXB
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 473900
- slug: product-473900
+ name: Product 576517
+ slug: product-576517
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -4991,37 +5396,37 @@ paths:
discounted_amount: '19.99'
display_discounted_amount: "$19.99"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:55:19.102Z'
- updated_at: '2026-03-10T11:55:19.187Z'
+ created_at: '2026-03-10T17:04:41.125Z'
+ updated_at: '2026-03-10T17:04:41.184Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_EfhxLZ9ck8
- number: H07809000212
+ number: H91036417779
state: pending
tracking:
tracking_url:
cost: '10.0'
display_cost: "$10.00"
shipped_at:
- created_at: '2026-03-10T11:55:19.207Z'
- updated_at: '2026-03-10T11:55:19.221Z'
+ created_at: '2026-03-10T17:04:41.203Z'
+ updated_at: '2026-03-10T17:04:41.216Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_203
- name: Elizabet Streich
+ state_abbr: STATE_ABBR_213
+ name: Antonietta Dare
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_203
+ state_text: STATE_ABBR_213
shipping_rates:
- id: shpr_EfhxLZ9ck8
shipping_method_id: shpm_UkLWZg9DAJ
@@ -5057,10 +5462,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_207
- state_abbr: STATE_ABBR_207
+ state_text: STATE_ABBR_217
+ state_abbr: STATE_ABBR_217
quick_checkout: false
- state_name: STATE_NAME_207
+ state_name: STATE_NAME_217
ship_address:
id: addr_OIJLhNcSbf
firstname: John
@@ -5074,10 +5479,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_208
- state_abbr: STATE_ABBR_208
+ state_text: STATE_ABBR_218
+ state_abbr: STATE_ABBR_218
quick_checkout: false
- state_name: STATE_NAME_208
+ state_name: STATE_NAME_218
payment_methods: []
schema:
"$ref": "#/components/schemas/Order"
@@ -5139,15 +5544,15 @@ paths:
application/json:
example:
id: or_gbHJdmfrXB
- number: R915653155
+ number: R254885749
state: complete
checkout_steps:
- address
- delivery
- payment
- complete
- token: DpGr8YnbKLQnMGzBiGPmKUmY8vTy3seHgwH
+ token: xEgPmTJp4LaXoKzpVAp9d3yin44132tQtgH
special_instructions:
currency: USD
locale: en
@@ -5171,17 +5576,17 @@ paths:
display_additional_tax_total: "$0.00"
total: '29.99'
display_total: "$29.99"
- completed_at: '2026-03-10T11:55:20.032Z'
- created_at: '2026-03-10T11:55:19.864Z'
- updated_at: '2026-03-10T11:55:20.032Z'
+ completed_at: '2026-03-10T17:04:42.124Z'
+ created_at: '2026-03-10T17:04:41.879Z'
+ updated_at: '2026-03-10T17:04:42.124Z'
order_promotions: []
line_items:
- id: li_gbHJdmfrXB
variant_id: variant_gbHJdmfrXB
quantity: 1
currency: USD
- name: Product 494798
- slug: product-494798
+ name: Product 59584
+ slug: product-59584
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -5200,37 +5605,37 @@ paths:
discounted_amount: '19.99'
display_discounted_amount: "$19.99"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:55:19.890Z'
- updated_at: '2026-03-10T11:55:19.932Z'
+ created_at: '2026-03-10T17:04:41.926Z'
+ updated_at: '2026-03-10T17:04:42.003Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_EfhxLZ9ck8
- number: H90634672570
+ number: H73037386882
state: pending
tracking:
tracking_url:
cost: '10.0'
display_cost: "$10.00"
shipped_at:
- created_at: '2026-03-10T11:55:19.950Z'
- updated_at: '2026-03-10T11:55:20.024Z'
+ created_at: '2026-03-10T17:04:42.023Z'
+ updated_at: '2026-03-10T17:04:42.114Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_209
- name: Toni Sipes
+ state_abbr: STATE_ABBR_219
+ name: Joe Batz
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_209
+ state_text: STATE_ABBR_219
shipping_rates:
- id: shpr_EfhxLZ9ck8
shipping_method_id: shpm_UkLWZg9DAJ
@@ -5257,11 +5662,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code: '12345'
- number: PB3UKFLL
+ number: PUULQOJO
amount: '29.99'
display_amount: "$29.99"
- created_at: '2026-03-10T11:55:19.999Z'
- updated_at: '2026-03-10T11:55:19.999Z'
+ created_at: '2026-03-10T17:04:42.085Z'
+ updated_at: '2026-03-10T17:04:42.085Z'
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
@@ -5292,10 +5697,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_213
- state_abbr: STATE_ABBR_213
+ state_text: STATE_ABBR_223
+ state_abbr: STATE_ABBR_223
quick_checkout: false
- state_name: STATE_NAME_213
+ state_name: STATE_NAME_223
ship_address:
id: addr_OIJLhNcSbf
firstname: John
@@ -5309,10 +5714,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_214
- state_abbr: STATE_ABBR_214
+ state_text: STATE_ABBR_224
+ state_abbr: STATE_ABBR_224
quick_checkout: false
- state_name: STATE_NAME_214
+ state_name: STATE_NAME_224
payment_methods:
- id: pm_UkLWZg9DAJ
name: Check
@@ -5494,13 +5899,13 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_1073a8602630d5b4b8b99eaf
+ external_id: bogus_24f80a115f6ec613a16db472
external_data:
- client_secret: bogus_secret_11ae245bd5f6ddb9
+ client_secret: bogus_secret_0fedf6cd8dcb6dd6
customer_external_id:
expires_at:
- created_at: '2026-03-10T11:55:22.475Z'
- updated_at: '2026-03-10T11:55:22.475Z'
+ created_at: '2026-03-10T17:04:44.552Z'
+ updated_at: '2026-03-10T17:04:44.552Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -5605,13 +6010,13 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_a5db209313ee104e829be877
+ external_id: bogus_e43d9b7f3cae456e4b5107ef
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-10T11:55:23.676Z'
- updated_at: '2026-03-10T11:55:23.676Z'
+ created_at: '2026-03-10T17:04:45.813Z'
+ updated_at: '2026-03-10T17:04:45.813Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -5668,13 +6073,13 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_836b7c860e316557e55dfdb1
+ external_id: bogus_53fe2325575c59a1333fcfd7
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-10T11:55:24.902Z'
- updated_at: '2026-03-10T11:55:24.917Z'
+ created_at: '2026-03-10T17:04:47.023Z'
+ updated_at: '2026-03-10T17:04:47.036Z'
amount: '50.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -5772,13 +6177,13 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_5e7d91a9a7ed8ba3278cbe8a
+ external_id: bogus_f134966162bb4f0c41d283b9
external_data:
client_secret: secret_123
customer_external_id:
expires_at:
- created_at: '2026-03-10T11:55:25.513Z'
- updated_at: '2026-03-10T11:55:25.525Z'
+ created_at: '2026-03-10T17:04:47.625Z'
+ updated_at: '2026-03-10T17:04:47.643Z'
amount: '110.0'
payment_method_id: pm_UkLWZg9DAJ
order_id: or_UkLWZg9DAJ
@@ -5858,11 +6263,11 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_96014046cb6502ea399736ce
- external_client_secret: bogus_seti_secret_43a828f046e14822
+ external_id: bogus_seti_f6b724b1c02fdc8ebe113469
+ external_client_secret: bogus_seti_secret_15978e14fbfe797c
external_data: {}
- created_at: '2026-03-10T11:55:26.707Z'
- updated_at: '2026-03-10T11:55:26.707Z'
+ created_at: '2026-03-10T17:04:48.865Z'
+ updated_at: '2026-03-10T17:04:48.865Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
payment_source_type:
@@ -5959,12 +6364,12 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_694fa0f1d2c7de73903c5e96
- external_client_secret: seti_secret_05ca8067b8bb039cfe4e08ae
+ external_id: seti_test_139f62554e1b1f886f9372f8
+ external_client_secret: seti_secret_896b7fff701a3b14c4a160f3
external_data:
client_secret: secret_123
- created_at: '2026-03-10T11:55:28.405Z'
- updated_at: '2026-03-10T11:55:28.405Z'
+ created_at: '2026-03-10T17:04:50.565Z'
+ updated_at: '2026-03-10T17:04:50.565Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
payment_source_type:
@@ -6037,12 +6442,12 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_0e186c60b0765ac924e4e3e6
- external_client_secret: seti_secret_d9c8cf06e9671063b845d776
+ external_id: seti_test_cb2bb23d0ca11478078d8a6f
+ external_client_secret: seti_secret_9526c4785711ff397d58f416
external_data:
client_secret: secret_123
- created_at: '2026-03-10T11:55:29.521Z'
- updated_at: '2026-03-10T11:55:29.536Z'
+ created_at: '2026-03-10T17:04:51.689Z'
+ updated_at: '2026-03-10T17:04:51.703Z'
payment_method_id: pm_UkLWZg9DAJ
payment_source_id: card_UkLWZg9DAJ
payment_source_type: Spree::CreditCard
@@ -6125,11 +6530,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code: '12345'
- number: PA4C9EZ6
+ number: PKKDJAF3
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-10T11:55:30.727Z'
- updated_at: '2026-03-10T11:55:30.727Z'
+ created_at: '2026-03-10T17:04:52.945Z'
+ updated_at: '2026-03-10T17:04:52.945Z'
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
@@ -6223,11 +6628,11 @@ paths:
payment_method_id: pm_UkLWZg9DAJ
state: checkout
response_code: '12345'
- number: P95PK6NV
+ number: PNYHVSO0
amount: '110.0'
display_amount: "$110.00"
- created_at: '2026-03-10T11:55:31.951Z'
- updated_at: '2026-03-10T11:55:31.951Z'
+ created_at: '2026-03-10T17:04:54.252Z'
+ updated_at: '2026-03-10T17:04:54.252Z'
source_type: credit_card
source_id: card_UkLWZg9DAJ
source:
@@ -6318,10 +6723,10 @@ paths:
description: Filter by name containing string
schema:
type: string
- - name: q[taxons_id_eq]
+ - name: q[categories_id_eq]
in: query
required: false
- description: Filter by taxon ID
+ description: Filter by category ID
schema:
type: string
- name: q[price_gte]
@@ -6352,7 +6757,7 @@ paths:
- name: expand
in: query
required: false
- description: Comma-separated associations to expand (variants, images, taxons,
+ description: Comma-separated associations to expand (variants, images, categories,
option_types)
schema:
type: string
@@ -6371,17 +6776,19 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 669834
+ name: Product 764489
description: |-
- Sapiente mollitia magni amet maxime explicabo sit minima. Necessitatibus architecto atque recusandae alias. Perspiciatis id vel laborum fugit. Laboriosam totam accusamus doloremque harum esse ipsam.
- Culpa voluptatum placeat numquam doloribus mollitia eligendi. Qui accusantium corporis voluptate autem quod. Laboriosam sed suscipit esse quod cumque quibusdam aperiam velit. Velit ex quis atque ratione vel. Deserunt atque alias sunt magni odio placeat.
- slug: product-669834
+ Provident nobis inventore ducimus odit. Ipsa non eos fugit odio dolorem repellat. Nobis earum nisi nulla alias adipisci quidem. Corporis eos eum et sint laboriosam reprehenderit. Quas doloribus inventore amet nemo.
+ Ducimus beatae sunt harum tempora. Mollitia reiciendis totam minus adipisci nostrum. Repellendus modi nulla quia a harum sapiente architecto.
+ Fuga placeat veniam provident excepturi. Placeat mollitia inventore excepturi dolorum molestiae. Voluptas nihil cupiditate aperiam aliquid.
+ Laudantium tempore nesciunt quaerat error fugit incidunt nisi. Eaque similique assumenda commodi quidem quas aspernatur. Qui magnam aspernatur deleniti nisi animi quod sint. Impedit sequi numquam molestias nam veniam distinctio alias iusto.
+ slug: product-764489
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-03-10T11:55:32.615Z'
- created_at: '2026-03-10T11:55:32.629Z'
- updated_at: '2026-03-10T11:55:32.668Z'
+ available_on: '2025-03-10T17:04:54.899Z'
+ created_at: '2026-03-10T17:04:54.914Z'
+ updated_at: '2026-03-10T17:04:54.956Z'
purchasable: true
in_stock: false
backorderable: true
@@ -6401,17 +6808,17 @@ paths:
price_list_id:
original_price:
- id: prod_gbHJdmfrXB
- name: Product 675677
+ name: Product 772269
description: |-
- Voluptas corporis ex nisi provident nobis ipsa maiores. Quos in dolor incidunt neque nam. Ad neque iure repellendus labore corrupti. Eaque inventore excepturi perferendis alias impedit neque aliquam nemo. Illum nisi laudantium veniam rerum blanditiis optio.
- Ducimus nesciunt repudiandae veritatis autem itaque vel enim voluptatem. Reprehenderit tempora voluptatum exercitationem omnis corporis. Distinctio earum dolor debitis suscipit eveniet enim odio minima. Rem recusandae tempore ad nihil incidunt. Harum quibusdam maiores atque eligendi saepe et.
- slug: product-675677
+ Quisquam totam libero consectetur quam illum occaecati sunt voluptatum. Deleniti molestias ipsum fugiat voluptatibus libero nulla. Sapiente hic commodi voluptatum sunt recusandae provident. Mollitia labore ipsum tenetur corporis voluptatum voluptatibus numquam voluptate.
+ Aliquam earum totam ea adipisci nihil minus harum. Animi adipisci sapiente quisquam molestias. Vel minima expedita iste perspiciatis eos esse voluptatibus. Quia molestiae veritatis explicabo dolore error ab maxime optio.
+ slug: product-772269
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-03-10T11:55:32.673Z'
- created_at: '2026-03-10T11:55:32.682Z'
- updated_at: '2026-03-10T11:55:32.694Z'
+ available_on: '2025-03-10T17:04:54.964Z'
+ created_at: '2026-03-10T17:04:54.975Z'
+ updated_at: '2026-03-10T17:04:54.990Z'
purchasable: true
in_stock: false
backorderable: true
@@ -6517,18 +6924,18 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 781639
+ name: Product 883743
description: |-
- Aliquid unde commodi asperiores hic. Non molestiae eius officiis repellendus nemo vero exercitationem. Adipisci ipsum quibusdam perspiciatis atque voluptatem architecto eaque.
- Atque a quibusdam impedit dicta possimus necessitatibus doloribus iste. Esse repudiandae voluptate adipisci aliquid sequi reiciendis fugit. Distinctio facere inventore alias deleniti occaecati. Delectus illo consequuntur debitis repellendus nihil asperiores fugiat.
- Quam quae voluptatibus libero perspiciatis adipisci ipsum inventore maiores. Sapiente suscipit qui doloremque aliquid animi. Velit ducimus consequatur distinctio dolorem.
- slug: product-781639
+ Tenetur laudantium omnis ab adipisci laboriosam. Atque earum iusto temporibus ipsam ullam. Qui dolore eius odit hic numquam excepturi corporis atque.
+ Mollitia voluptate possimus non consectetur at excepturi occaecati quod. Ullam aut perferendis voluptatem dolor asperiores corrupti reprehenderit. Eaque repudiandae et quos officiis mollitia eum. In velit inventore quasi ipsum.
+ Molestias tempore vero consectetur delectus exercitationem maiores nulla. Minus blanditiis excepturi cupiditate ut. Reiciendis cumque nisi nihil maxime. Eum fuga ipsa porro earum consequuntur omnis nihil. Molestiae enim dicta soluta doloremque.
+ slug: product-883743
meta_description:
meta_keywords:
variant_count: 1
- available_on: '2025-03-10T11:55:33.399Z'
- created_at: '2026-03-10T11:55:33.412Z'
- updated_at: '2026-03-10T11:55:33.444Z'
+ available_on: '2025-03-10T17:04:55.491Z'
+ created_at: '2026-03-10T17:04:55.504Z'
+ updated_at: '2026-03-10T17:04:55.535Z'
purchasable: true
in_stock: false
backorderable: true
@@ -6570,8 +6977,8 @@ paths:
Returns available filters for products with their options and counts.
Use this endpoint to build filter UIs for product listing pages.
- The filters are context-aware - when a taxon_id is provided, only filters
- relevant to products in that taxon are returned.
+ The filters are context-aware - when a category_id is provided, only filters
+ relevant to products in that category are returned.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -6584,7 +6991,7 @@ paths:
})
const filters = await client.products.filters({
- taxon_id: 'taxon_abc123',
+ category_id: 'ctg_abc123',
})
parameters:
- name: x-spree-api-key
@@ -6593,10 +7000,10 @@ paths:
description: Publishable API key
schema:
type: string
- - name: taxon_id
+ - name: category_id
in: query
required: false
- description: Scope filters to products in this taxon (prefix ID)
+ description: Scope filters to products in this category (prefix ID)
schema:
type: string
- name: q[name_cont]
@@ -6607,7 +7014,7 @@ paths:
type: string
responses:
'200':
- description: filters scoped to taxon
+ description: filters scoped to category
content:
application/json:
example:
@@ -6634,12 +7041,12 @@ paths:
presentation: S
position: 1
count: 1
- - id: taxons
- type: taxon
+ - id: categories
+ type: category
options:
- - id: txn_p6klVeMgbn
+ - id: ctg_EfhxLZ9ck8
name: Shirts
- permalink: taxonomy-9/taxon-9/shirts
+ permalink: taxonomy-29/taxon-39/shirts
count: 2
sort_options:
- id: manual
@@ -6658,7 +7065,7 @@ paths:
filters:
type: array
description: Available filters (price_range, availability, option,
- taxon)
+ category)
items:
type: object
sort_options:
@@ -6745,29 +7152,29 @@ paths:
example:
data:
- id: ship_UkLWZg9DAJ
- number: H55655865075
+ number: H95308138645
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-10T11:55:35.946Z'
- updated_at: '2026-03-10T11:55:35.958Z'
+ created_at: '2026-03-10T17:04:57.456Z'
+ updated_at: '2026-03-10T17:04:57.472Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_295
- name: Mindy Howe
+ state_abbr: STATE_ABBR_305
+ name: Buddy Harvey
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_295
+ state_text: STATE_ABBR_305
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -6858,29 +7265,29 @@ paths:
application/json:
example:
id: ship_UkLWZg9DAJ
- number: H85904307063
+ number: H32342050285
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-10T11:55:37.148Z'
- updated_at: '2026-03-10T11:55:37.161Z'
+ created_at: '2026-03-10T17:04:58.669Z'
+ updated_at: '2026-03-10T17:04:58.682Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_303
- name: Danilo Torphy
+ state_abbr: STATE_ABBR_313
+ name: Barbie Beier
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_303
+ state_text: STATE_ABBR_313
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -6964,15 +7371,15 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R101880373
+ number: R547955671
state: delivery
checkout_steps:
- address
- delivery
- payment
- complete
- token: fbGk4m3mzQz3Y7KXEXMgx7UaGQQwZAiUncV
+ token: s2D3AWULn6SZ3HbP3KZBD7Nq3mXzjZdhSFh
special_instructions:
currency: USD
locale: en
@@ -6997,16 +7404,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-10T11:55:38.305Z'
- updated_at: '2026-03-10T11:55:38.371Z'
+ created_at: '2026-03-10T17:04:59.849Z'
+ updated_at: '2026-03-10T17:04:59.914Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1107366
- slug: product-1107366
+ name: Product 1209434
+ slug: product-1209434
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -7025,37 +7432,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:55:38.333Z'
- updated_at: '2026-03-10T11:55:38.333Z'
+ created_at: '2026-03-10T17:04:59.878Z'
+ updated_at: '2026-03-10T17:04:59.878Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H31897070954
+ number: H39630301795
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-10T11:55:38.338Z'
- updated_at: '2026-03-10T11:55:38.370Z'
+ created_at: '2026-03-10T17:04:59.883Z'
+ updated_at: '2026-03-10T17:04:59.913Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_311
- name: Isis Wuckert
+ state_abbr: STATE_ABBR_321
+ name: Rebekah Goyette
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_311
+ state_text: STATE_ABBR_321
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -7081,10 +7488,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_313
- state_abbr: STATE_ABBR_313
+ state_text: STATE_ABBR_323
+ state_abbr: STATE_ABBR_323
quick_checkout: false
- state_name: STATE_NAME_313
+ state_name: STATE_NAME_323
ship_address:
id: addr_VqXmZF31wY
firstname: John
@@ -7098,10 +7505,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_314
- state_abbr: STATE_ABBR_314
+ state_text: STATE_ABBR_324
+ state_abbr: STATE_ABBR_324
quick_checkout: false
- state_name: STATE_NAME_314
+ state_name: STATE_NAME_324
payment_methods: []
schema:
"$ref": "#/components/schemas/Order"
@@ -7186,15 +7593,15 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R714649010
+ number: R034719281
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: BMzmffdzwk8ozoSEcz6WaQo5FX3PpJZWLgi
+ token: SWzRTQLxVE7NHxc6G299YfvCeXWP2MHyg9w
special_instructions:
currency: USD
locale: en
@@ -7219,16 +7626,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-10T11:55:39.533Z'
- updated_at: '2026-03-10T11:55:39.586Z'
+ created_at: '2026-03-10T17:05:01.116Z'
+ updated_at: '2026-03-10T17:05:01.199Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1129368
- slug: product-1129368
+ name: Product 1223187
+ slug: product-1223187
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -7247,37 +7654,37 @@ paths:
discounted_amount: '10.0'
display_discounted_amount: "$10.00"
display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:55:39.566Z'
- updated_at: '2026-03-10T11:55:39.566Z'
+ created_at: '2026-03-10T17:05:01.172Z'
+ updated_at: '2026-03-10T17:05:01.172Z'
compare_at_amount:
thumbnail_url:
option_values: []
digital_links: []
shipments:
- id: ship_UkLWZg9DAJ
- number: H75250389465
+ number: H16218442175
state: pending
tracking: U10000
tracking_url:
cost: '100.0'
display_cost: "$100.00"
shipped_at:
- created_at: '2026-03-10T11:55:39.571Z'
- updated_at: '2026-03-10T11:55:39.584Z'
+ created_at: '2026-03-10T17:05:01.180Z'
+ updated_at: '2026-03-10T17:05:01.197Z'
shipping_method:
id: shpm_UkLWZg9DAJ
name: UPS Ground
code: UPS_GROUND
stock_location:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_319
- name: Trang Emmerich
+ state_abbr: STATE_ABBR_329
+ name: Paige Koss
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_319
+ state_text: STATE_ABBR_329
shipping_rates:
- id: shpr_UkLWZg9DAJ
shipping_method_id: shpm_UkLWZg9DAJ
@@ -7293,12 +7700,12 @@ paths:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
state: checkout
- response_code: 1-SC-20260310115539883880
- number: PU4WV5IO
+ response_code: 1-SC-20260310170501502405
+ number: P4IT9OGA
amount: '10.0'
display_amount: "$10.00"
- created_at: '2026-03-10T11:55:39.887Z'
- updated_at: '2026-03-10T11:55:39.887Z'
+ created_at: '2026-03-10T17:05:01.505Z'
+ updated_at: '2026-03-10T17:05:01.505Z'
source_type: store_credit
source_id: credit_UkLWZg9DAJ
source:
@@ -7329,10 +7736,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_321
- state_abbr: STATE_ABBR_321
+ state_text: STATE_ABBR_331
+ state_abbr: STATE_ABBR_331
quick_checkout: false
- state_name: STATE_NAME_321
+ state_name: STATE_NAME_331
ship_address:
id: addr_VqXmZF31wY
firstname: John
@@ -7346,10 +7753,10 @@ paths:
company: Company
country_name: United States of America
country_iso: US
- state_text: STATE_ABBR_322
- state_abbr: STATE_ABBR_322
+ state_text: STATE_ABBR_332
+ state_abbr: STATE_ABBR_332
quick_checkout: false
- state_name: STATE_NAME_322
+ state_name: STATE_NAME_332
payment_methods:
- id: pm_UkLWZg9DAJ
name: Store Credit
@@ -7428,15 +7835,15 @@ paths:
application/json:
example:
id: or_UkLWZg9DAJ
- number: R295696333
+ number: R734318424
state: cart
checkout_steps:
- address
- delivery
- payment
- complete
- token: ksKXd34aabjHYBUV1paLeJfw34bYSySHfXF
+ token: jHD2wZotmK4yfCSCq7sumARkEXiSET3GKU4
special_instructions:
currency: USD
locale: en
@@ -7461,16 +7868,16 @@ paths:
total: '110.0'
display_total: "$110.00"
completed_at:
- created_at: '2026-03-10T11:55:41.047Z'
- updated_at: '2026-03-10T11:55:41.095Z'
+ created_at: '2026-03-10T17:05:02.666Z'
+ updated_at: '2026-03-10T17:05:02.717Z'
order_promotions: []
line_items:
- id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
quantity: 1
currency: USD
- name: Product 1142757
- slug: product-1142757
+ name: Product 1245816
+ slug: product-1245816
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -7483,799 +7890,92 @@ paths:
included_tax_total: '0.0'
display_included_tax_total: "$0.00"
promo_total: '0.0'
- display_promo_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- created_at: '2026-03-10T11:55:41.076Z'
- updated_at: '2026-03-10T11:55:41.076Z'
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- shipments:
- - id: ship_UkLWZg9DAJ
- number: H36522257617
- state: pending
- tracking: U10000
- tracking_url:
- cost: '100.0'
- display_cost: "$100.00"
- shipped_at:
- created_at: '2026-03-10T11:55:41.081Z'
- updated_at: '2026-03-10T11:55:41.093Z'
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- stock_location:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_327
- name: Ling Schmidt
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_iso: US
- country_name: United States of America
- state_text: STATE_ABBR_327
- shipping_rates:
- - id: shpr_UkLWZg9DAJ
- shipping_method_id: shpm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '100.0'
- display_cost: "$100.00"
- shipping_method:
- id: shpm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- payments: []
- bill_address:
- id: addr_EfhxLZ9ck8
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 318 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_329
- state_abbr: STATE_ABBR_329
- quick_checkout: false
- state_name: STATE_NAME_329
- ship_address:
- id: addr_VqXmZF31wY
- firstname: John
- lastname: Doe
- full_name: John Doe
- address1: 319 Lovely Street
- address2: Northwest
- city: Herndon
- zipcode: '35005'
- phone: 555-555-0199
- company: Company
- country_name: United States of America
- country_iso: US
- state_text: STATE_ABBR_330
- state_abbr: STATE_ABBR_330
- quick_checkout: false
- state_name: STATE_NAME_330
- payment_methods: []
- schema:
- "$ref": "#/components/schemas/Order"
- "/api/v3/store/taxonomies":
- get:
- summary: List taxonomies
- tags:
- - Product Catalog
- security:
- - api_key: []
- description: Returns a list of taxonomies (category hierarchies) for the current
- store
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const taxonomies = await client.taxonomies.list({
- page: 1,
- limit: 25,
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: page
- in: query
- required: false
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: sort
- in: query
- required: false
- description: 'Sort order. Prefix with - for descending. Example: name, -name'
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Expand root taxon
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
- responses:
- '200':
- description: taxonomies found
- content:
- application/json:
- example:
- data:
- - id: txnmy_UkLWZg9DAJ
- name: Categories
- position: 1
- created_at: '2026-03-10T11:54:38.263Z'
- updated_at: '2026-03-10T11:54:38.286Z'
- root_id: txn_UkLWZg9DAJ
- - id: txnmy_gbHJdmfrXB
- name: Brands
- position: 2
- created_at: '2026-03-10T11:54:38.287Z'
- updated_at: '2026-03-10T11:54:38.295Z'
- root_id: txn_gbHJdmfrXB
- - id: txnmy_EfhxLZ9ck8
- name: Collections
- position: 3
- created_at: '2026-03-10T11:54:38.296Z'
- updated_at: '2026-03-10T11:54:38.353Z'
- root_id: txn_EfhxLZ9ck8
- - id: txnmy_VqXmZF31wY
- name: taxonomy_11
- position: 4
- created_at: '2026-03-10T11:55:41.126Z'
- updated_at: '2026-03-10T11:55:41.134Z'
- root_id: txn_OIJLhNcSbf
- - id: txnmy_uw2YK1rnl0
- name: taxonomy_12
- position: 5
- created_at: '2026-03-10T11:55:41.135Z'
- updated_at: '2026-03-10T11:55:41.141Z'
- root_id: txn_AXs1igzRC6
- meta:
- page: 1
- limit: 25
- count: 5
- pages: 1
- from: 1
- to: 5
- in: 5
- previous:
- next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Taxonomy"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: invalid_token
- message: Valid API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/taxonomies/{id}":
- get:
- summary: Get a taxonomy
- tags:
- - Product Catalog
- security:
- - api_key: []
- description: Returns a single taxonomy with its taxon tree
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const taxonomy = await client.taxonomies.get('taxonomy_abc123', {
- expand: 'taxons',
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Taxonomy ID (prefixed)
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Expand taxons
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
- responses:
- '200':
- description: taxonomy found
- content:
- application/json:
- example:
- id: txnmy_VqXmZF31wY
- name: taxonomy_17
- position: 4
- created_at: '2026-03-10T11:55:41.364Z'
- updated_at: '2026-03-10T11:55:41.372Z'
- root_id: txn_OIJLhNcSbf
- schema:
- "$ref": "#/components/schemas/Taxonomy"
- '404':
- description: taxonomy from other store
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Couldn't find Spree::Taxonomy with 'id'=9 [WHERE "spree_taxonomies"."store_id"
- = ?]
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/taxons":
- get:
- summary: List taxons
- tags:
- - Product Catalog
- security:
- - api_key: []
- description: Returns a paginated list of taxons (categories) for the current
- store
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const taxons = await client.taxons.list({
- page: 1,
- limit: 25,
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: page
- in: query
- required: false
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: q[name_cont]
- in: query
- required: false
- description: Filter by name
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
- responses:
- '200':
- description: taxons found
- content:
- application/json:
- example:
- data:
- - id: txn_UkLWZg9DAJ
- name: Categories
- permalink: categories
- position: 0
- depth: 0
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-10T11:54:38.274Z'
- updated_at: '2026-03-10T11:54:38.284Z'
- parent_id:
- taxonomy_id: txnmy_UkLWZg9DAJ
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: true
- is_child: false
- is_leaf: true
- - id: txn_gbHJdmfrXB
- name: Brands
- permalink: brands
- position: 0
- depth: 0
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-10T11:54:38.290Z'
- updated_at: '2026-03-10T11:54:38.294Z'
- parent_id:
- taxonomy_id: txnmy_gbHJdmfrXB
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: true
- is_child: false
- is_leaf: true
- - id: txn_EfhxLZ9ck8
- name: Collections
- permalink: collections
- position: 0
- depth: 0
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 2
- created_at: '2026-03-10T11:54:38.299Z'
- updated_at: '2026-03-10T11:54:38.353Z'
- parent_id:
- taxonomy_id: txnmy_EfhxLZ9ck8
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: true
- is_child: false
- is_leaf: false
- - id: txn_VqXmZF31wY
- name: On sale
- permalink: collections/on-sale
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-10T11:54:38.312Z'
- updated_at: '2026-03-10T11:54:38.314Z'
- parent_id: txn_EfhxLZ9ck8
- taxonomy_id: txnmy_EfhxLZ9ck8
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- - id: txn_uw2YK1rnl0
- name: New arrivals
- permalink: collections/new-arrivals
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-10T11:54:38.324Z'
- updated_at: '2026-03-10T11:54:38.326Z'
- parent_id: txn_EfhxLZ9ck8
- taxonomy_id: txnmy_EfhxLZ9ck8
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- - id: txn_OIJLhNcSbf
- name: taxonomy_26
- permalink: taxonomy-26
- position: 0
- depth: 0
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 1
- created_at: '2026-03-10T11:55:41.783Z'
- updated_at: '2026-03-10T11:55:41.850Z'
- parent_id:
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: true
- is_child: false
- is_leaf: false
- - id: txn_AXs1igzRC6
- name: taxon_11
- permalink: taxonomy-26/taxon-11
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 1
- created_at: '2026-03-10T11:55:41.797Z'
- updated_at: '2026-03-10T11:55:41.850Z'
- parent_id: txn_OIJLhNcSbf
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: false
- - id: txn_p6klVeMgbn
- name: taxon_12
- permalink: taxonomy-26/taxon-11/taxon-12
- position: 0
- depth: 2
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 0
- created_at: '2026-03-10T11:55:41.815Z'
- updated_at: '2026-03-10T11:55:41.822Z'
- parent_id: txn_AXs1igzRC6
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: true
- meta:
- page: 1
- limit: 25
- count: 8
- pages: 1
- from: 1
- to: 8
- in: 8
- previous:
- next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Taxon"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: invalid_token
- message: Valid API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/taxons/{id}":
- get:
- summary: Get a taxon
- tags:
- - Product Catalog
- security:
- - api_key: []
- description: Returns a single taxon by permalink or prefix ID
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const taxon = await client.taxons.get('categories/clothing/shirts', {
- expand: 'children,products',
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Taxon permalink (e.g., categories/clothing/shirts) or prefix
- ID (e.g., taxon_abc123)
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Expand associations (children, products, parent)
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
- responses:
- '200':
- description: taxon found by prefix ID
- content:
- application/json:
- example:
- id: txn_AXs1igzRC6
- name: taxon_20
- permalink: taxonomy-32/taxon-20
- position: 0
- depth: 1
- meta_title:
- meta_description:
- meta_keywords:
- children_count: 1
- created_at: '2026-03-10T11:55:42.349Z'
- updated_at: '2026-03-10T11:55:42.382Z'
- parent_id: txn_OIJLhNcSbf
- taxonomy_id: txnmy_VqXmZF31wY
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- is_root: false
- is_child: true
- is_leaf: false
- schema:
- "$ref": "#/components/schemas/Taxon"
- '404':
- description: taxon from other store not accessible
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Taxon not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: invalid_token
- message: Valid API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/taxons/{taxon_id}/products":
- get:
- summary: List products in a taxon
- tags:
- - Product Catalog
- security:
- - api_key: []
- description: Returns a paginated list of products belonging to the specified
- taxon
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const products = await client.taxons.products.list('categories/clothing', {
- page: 1,
- limit: 25,
- sort: 'price',
- with_option_value_ids: ['optval_abc'],
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: taxon_id
- in: path
- required: true
- description: Taxon permalink or prefix ID
- schema:
- type: string
- - name: page
- in: query
- required: false
- description: 'Page number (default: 1)'
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- description: 'Number of items per page (default: 25, max: 100)'
- schema:
- type: integer
- - name: sort
- in: query
- required: false
- description: 'Sort order. Prefix with - for descending. Values: price, -price,
- best_selling, name, -name, -available_on, available_on'
- schema:
- type: string
- - name: q[price_gte]
- in: query
- required: false
- description: Filter by minimum price
- schema:
- type: number
- - name: q[price_lte]
- in: query
- required: false
- description: Filter by maximum price
- schema:
- type: number
- - name: q[with_option_value_ids][]
- in: query
- required: false
- description: Filter by option value prefix IDs
- schema:
- type: string
- - name: q[in_stock]
- in: query
- required: false
- description: Filter to only in-stock products
- schema:
- type: boolean
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
- responses:
- '200':
- description: products found
- content:
- application/json:
- example:
- data:
- - id: prod_UkLWZg9DAJ
- name: Product 1223974
- description: A esse nostrum cupiditate corrupti ut. Voluptate illum
- natus alias veniam similique dicta. Assumenda minus consequuntur
- debitis eos unde soluta repellendus. Vero quis adipisci aut consequatur
- laborum nobis odit ullam. Nemo corporis dolores velit expedita.
- slug: product-1223974
- meta_description:
- meta_keywords:
- variant_count: 0
- available_on: '2025-03-10T11:55:43.135Z'
- created_at: '2026-03-10T11:55:43.152Z'
- updated_at: '2026-03-10T11:55:43.167Z'
- purchasable: true
- in_stock: false
- backorderable: true
- available: true
- default_variant_id: variant_UkLWZg9DAJ
- thumbnail_url:
- tags: []
- price:
- id: price_UkLWZg9DAJ
- amount: '19.99'
- amount_in_cents: 1999
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$19.99"
- display_compare_at_amount:
- price_list_id:
- original_price:
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Product"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '404':
- description: taxon not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Taxon not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: invalid_token
- message: Valid API key required
+ display_promo_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ created_at: '2026-03-10T17:05:02.695Z'
+ updated_at: '2026-03-10T17:05:02.695Z'
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ shipments:
+ - id: ship_UkLWZg9DAJ
+ number: H38993011835
+ state: pending
+ tracking: U10000
+ tracking_url:
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipped_at:
+ created_at: '2026-03-10T17:05:02.701Z'
+ updated_at: '2026-03-10T17:05:02.715Z'
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ state_abbr: STATE_ABBR_337
+ name: Allyn Yost
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_iso: US
+ country_name: United States of America
+ state_text: STATE_ABBR_337
+ shipping_rates:
+ - id: shpr_UkLWZg9DAJ
+ shipping_method_id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '100.0'
+ display_cost: "$100.00"
+ shipping_method:
+ id: shpm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ payments: []
+ bill_address:
+ id: addr_EfhxLZ9ck8
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 318 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_339
+ state_abbr: STATE_ABBR_339
+ quick_checkout: false
+ state_name: STATE_NAME_339
+ ship_address:
+ id: addr_VqXmZF31wY
+ firstname: John
+ lastname: Doe
+ full_name: John Doe
+ address1: 319 Lovely Street
+ address2: Northwest
+ city: Herndon
+ zipcode: '35005'
+ phone: 555-555-0199
+ company: Company
+ country_name: United States of America
+ country_iso: US
+ state_text: STATE_ABBR_340
+ state_abbr: STATE_ABBR_340
+ quick_checkout: false
+ state_name: STATE_NAME_340
+ payment_methods: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/Order"
"/api/v3/store/wishlists":
get:
summary: List wishlists
@@ -8336,9 +8036,9 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: a1GwMte6YrhjNreJVRkmVvUc
- created_at: '2026-03-10T11:55:44.167Z'
- updated_at: '2026-03-10T11:55:44.167Z'
+ token: 6m4ZLjk8tFGtqQvMQBYDcXir
+ created_at: '2026-03-10T17:05:03.274Z'
+ updated_at: '2026-03-10T17:05:03.274Z'
is_default: false
is_private: true
meta:
@@ -8414,9 +8114,9 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: kSvxCTWPNPGyNQM8TGVs7UJk
- created_at: '2026-03-10T11:55:45.342Z'
- updated_at: '2026-03-10T11:55:45.342Z'
+ token: XTM6UEAmnkHpxGLg8VQwWri4
+ created_at: '2026-03-10T17:05:04.454Z'
+ updated_at: '2026-03-10T17:05:04.454Z'
is_default: false
is_private: true
schema:
@@ -8512,9 +8212,9 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: 8udJKC7sqg66f51niguK5k9S
- created_at: '2026-03-10T11:55:46.449Z'
- updated_at: '2026-03-10T11:55:46.449Z'
+ token: vw9isW8Gr8x3Xugbk7qRA2Kg
+ created_at: '2026-03-10T17:05:05.633Z'
+ updated_at: '2026-03-10T17:05:05.633Z'
is_default: false
is_private: true
schema:
@@ -8576,9 +8276,9 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: Qn2NbKuCbfZEYud1sPKPgihL
- created_at: '2026-03-10T11:55:47.583Z'
- updated_at: '2026-03-10T11:55:47.626Z'
+ token: MRjk3FQKq28nzNSYn6R4Y4DZ
+ created_at: '2026-03-10T17:05:06.816Z'
+ updated_at: '2026-03-10T17:05:06.871Z'
is_default: false
is_private: true
schema:
@@ -8690,8 +8390,8 @@ paths:
variant_id: variant_gbHJdmfrXB
wishlist_id: wl_UkLWZg9DAJ
quantity: 1
- created_at: '2026-03-10T11:55:48.799Z'
- updated_at: '2026-03-10T11:55:48.799Z'
+ created_at: '2026-03-10T17:05:08.111Z'
+ updated_at: '2026-03-10T17:05:08.111Z'
variant:
id: variant_gbHJdmfrXB
product_id: prod_gbHJdmfrXB
@@ -8700,8 +8400,8 @@ paths:
options_text: ''
track_inventory: true
image_count: 0
- created_at: '2026-03-10T11:55:48.767Z'
- updated_at: '2026-03-10T11:55:48.781Z'
+ created_at: '2026-03-10T17:05:08.084Z'
+ updated_at: '2026-03-10T17:05:08.096Z'
thumbnail:
purchasable: true
in_stock: false
@@ -9055,6 +8755,88 @@ components:
required:
- id
x-typelizer: true
+ Category:
+ type: object
+ properties:
+ id:
+ type: string
+ name:
+ type: string
+ permalink:
+ type: string
+ position:
+ type: number
+ depth:
+ type: number
+ meta_title:
+ type: string
+ nullable: true
+ meta_description:
+ type: string
+ nullable: true
+ meta_keywords:
+ type: string
+ nullable: true
+ children_count:
+ type: number
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ parent_id:
+ type: string
+ nullable: true
+ description:
+ type: string
+ description_html:
+ type: string
+ image_url:
+ type: string
+ nullable: true
+ square_image_url:
+ type: string
+ nullable: true
+ is_root:
+ type: boolean
+ is_child:
+ type: boolean
+ is_leaf:
+ type: boolean
+ parent:
+ "$ref": "#/components/schemas/Category"
+ children:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Category"
+ ancestors:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Category"
+ metafields:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Metafield"
+ required:
+ - id
+ - name
+ - permalink
+ - position
+ - depth
+ - meta_title
+ - meta_description
+ - meta_keywords
+ - children_count
+ - created_at
+ - updated_at
+ - parent_id
+ - description
+ - description_html
+ - image_url
+ - square_image_url
+ - is_root
+ - is_child
+ - is_leaf
+ x-typelizer: true
Country:
type: object
properties:
@@ -10260,10 +10042,10 @@ components:
type: array
items:
"$ref": "#/components/schemas/OptionType"
- taxons:
+ categories:
type: array
items:
- "$ref": "#/components/schemas/Taxon"
+ "$ref": "#/components/schemas/Category"
metafields:
type: array
items:
@@ -10833,125 +10615,6 @@ components:
- id
- name
x-typelizer: true
- Taxon:
- type: object
- properties:
- id:
- type: string
- name:
- type: string
- permalink:
- type: string
- position:
- type: number
- depth:
- type: number
- meta_title:
- type: string
- nullable: true
- meta_description:
- type: string
- nullable: true
- meta_keywords:
- type: string
- nullable: true
- children_count:
- type: number
- created_at:
- type: string
- updated_at:
- type: string
- parent_id:
- type: string
- nullable: true
- taxonomy_id:
- type: string
- description:
- type: string
- description_html:
- type: string
- image_url:
- type: string
- nullable: true
- square_image_url:
- type: string
- nullable: true
- is_root:
- type: boolean
- is_child:
- type: boolean
- is_leaf:
- type: boolean
- parent:
- "$ref": "#/components/schemas/Taxon"
- children:
- type: array
- items:
- "$ref": "#/components/schemas/Taxon"
- ancestors:
- type: array
- items:
- "$ref": "#/components/schemas/Taxon"
- metafields:
- type: array
- items:
- "$ref": "#/components/schemas/Metafield"
- required:
- - id
- - name
- - permalink
- - position
- - depth
- - meta_title
- - meta_description
- - meta_keywords
- - children_count
- - created_at
- - updated_at
- - parent_id
- - taxonomy_id
- - description
- - description_html
- - image_url
- - square_image_url
- - is_root
- - is_child
- - is_leaf
- x-typelizer: true
- Taxonomy:
- type: object
- properties:
- id:
- type: string
- name:
- type: string
- position:
- type: number
- created_at:
- type: string
- updated_at:
- type: string
- root_id:
- type: string
- nullable: true
- root:
- "$ref": "#/components/schemas/Taxon"
- taxons:
- type: array
- items:
- "$ref": "#/components/schemas/Taxon"
- metafields:
- type: array
- items:
- "$ref": "#/components/schemas/Metafield"
- required:
- - id
- - name
- - position
- - created_at
- - updated_at
- - root_id
- x-typelizer: true
Variant:
type: object
properties:
diff --git a/docs/developer/core-concepts/products.mdx b/docs/developer/core-concepts/products.mdx
index 9dbfa7e868..87dc2adabd 100644
--- a/docs/developer/core-concepts/products.mdx
+++ b/docs/developer/core-concepts/products.mdx
@@ -7,7 +7,7 @@ description: Products, variants, option types, images, prices, and categories
A product represents something you sell. Each product has one or more **variants** — the actual purchasable items with their own SKU, price, and inventory. For example, a "T-Shirt" product might have variants for each size and color combination.
-Products are organized into categories using **taxonomies** and **taxons**, and can be filtered, sorted, and searched via the Store API.
+Products are organized into **categories** — a flexible hierarchy for grouping products. Categories can be filtered, sorted, and searched via the Store API.
<Info>
Product names, descriptions, slugs, and SEO fields are [translatable](/developer/core-concepts/translations#resource-translations).
@@ -133,7 +133,7 @@ const product = await client.products.get('spree-tote')
// Get with included relations
const detailed = await client.products.get('spree-tote', {
- expand: ['variants', 'images', 'option_types', 'taxons'],
+ expand: ['variants', 'images', 'option_types', 'categories'],
})
// detailed.variants => [{ id: "var_xxx", sku: "TOTE-S-R", price: { amount: "15.99", currency: "USD" }, ... }]
// detailed.images => [{ id: "img_xxx", url: "https://cdn...", position: 1 }]
@@ -141,7 +141,7 @@ const detailed = await client.products.get('spree-tote', {
```
```bash cURL
-curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,images,option_types,taxons' \
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,images,option_types,categories' \
-H 'Authorization: Bearer spree_pk_xxx'
```
@@ -149,7 +149,7 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,i
## Product Filters
-Get available filter options for building a faceted search UI. Returns price ranges, option values, and taxons with counts:
+Get available filter options for building a faceted search UI. Returns price ranges, option values, and categories with counts:
<CodeGroup>
@@ -158,12 +158,12 @@ const filters = await client.products.filters()
// {
// option_types: [{ name: "size", option_values: [{ name: "Small", count: 12 }, ...] }],
// price_range: { min: 9.99, max: 199.99 },
-// taxons: [{ id: "txn_xxx", name: "Clothing", count: 45 }],
+// categories: [{ id: "ctg_xxx", name: "Clothing", count: 45 }],
// }
-// Scoped to a specific taxon
-const taxonFilters = await client.products.filters({
- taxon_id_eq: 'txn_xxx',
+// Scoped to a specific category
+const categoryFilters = await client.products.filters({
+ category_id: 'ctg_xxx',
})
```
@@ -171,8 +171,8 @@ const taxonFilters = await client.products.filters({
curl 'https://api.mystore.com/api/v3/store/products/filters' \
-H 'Authorization: Bearer spree_pk_xxx'
-# Scoped to a taxon
-curl 'https://api.mystore.com/api/v3/store/products/filters?taxon_id_eq=txn_xxx' \
+# Scoped to a category
+curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
-H 'Authorization: Bearer spree_pk_xxx'
```
@@ -326,57 +326,50 @@ The API automatically returns the correct price based on the current currency an
See the [Pricing](/developer/core-concepts/pricing) guide for details on Price Lists, Price Rules, and market-specific pricing.
-## Taxons and Taxonomies
+## Categories
-Taxonomies provide a flexible way to categorize products. A **taxonomy** is a hierarchical category tree, and a **taxon** is a node within that tree.
+Categories provide a flexible way to organize products into hierarchical trees. Internally, Spree uses Taxonomies (category trees) and Taxons (nodes within those trees), but the Store API exposes them simply as **Categories**.
For example:
-- **Categories** (taxonomy) → Clothing → T-Shirts, Dresses
-- **Brands** (taxonomy) → Nike, Adidas, Puma
-- **Collections** (taxonomy) → Summer 2025, Best Sellers
+- **Categories** → Clothing → T-Shirts, Dresses
+- **Brands** → Nike, Adidas, Puma
+- **Collections** → Summer 2025, Best Sellers
-Products can belong to multiple taxons across different taxonomies.
+Products can belong to multiple categories.
<CodeGroup>
```typescript SDK
-// List taxonomies
-const { data: taxonomies } = await client.taxonomies.list()
+// List categories
+const { data: categories } = await client.categories.list()
-// List taxons (categories)
-const { data: taxons } = await client.taxons.list()
+// Get a category by permalink
+const category = await client.categories.get('clothing/shirts')
-// Get a taxon by permalink
-const taxon = await client.taxons.get('categories/clothing')
-
-// List products in a taxon
-const { data: products } = await client.taxons.products.list('categories/clothing', {
+// List products in a category
+const { data: products } = await client.categories.products.list('clothing/shirts', {
limit: 12,
})
```
```bash cURL
-# List taxonomies
-curl 'https://api.mystore.com/api/v3/store/taxonomies' \
- -H 'Authorization: Bearer spree_pk_xxx'
-
-# List taxons
-curl 'https://api.mystore.com/api/v3/store/taxons' \
+# List categories
+curl 'https://api.mystore.com/api/v3/store/categories' \
-H 'Authorization: Bearer spree_pk_xxx'
-# Get a taxon by permalink
-curl 'https://api.mystore.com/api/v3/store/taxons/categories/clothing' \
+# Get a category by permalink
+curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts' \
-H 'Authorization: Bearer spree_pk_xxx'
-# List products in a taxon
-curl 'https://api.mystore.com/api/v3/store/taxons/categories/clothing/products?limit=12' \
+# List products in a category
+curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
-H 'Authorization: Bearer spree_pk_xxx'
```
</CodeGroup>
<Info>
-Taxon `name` and `description` fields are translatable.
+Category `name` and `description` fields are translatable.
</Info>
## Related Documentation
diff --git a/docs/developer/core-concepts/search-filtering.mdx b/docs/developer/core-concepts/search-filtering.mdx
index 961678668b..fd0d956d79 100644
--- a/docs/developer/core-concepts/search-filtering.mdx
+++ b/docs/developer/core-concepts/search-filtering.mdx
@@ -70,29 +70,29 @@ curl 'https://api.mystore.com/api/v3/store/products?q[in_stock]=true' \
</CodeGroup>
-### By Category (Taxon)
+### By Category
<CodeGroup>
```typescript SDK
// Products in a specific category
-const { data: products } = await client.taxons.products.list('categories/clothing', {
+const { data: products } = await client.categories.products.list('clothing/shirts', {
limit: 12,
})
-// Or filter by taxon ID
+// Or filter by category ID
const { data: products } = await client.products.list({
- taxon_id_eq: 'txn_xxx',
+ categories_id_eq: 'ctg_xxx',
})
```
```bash cURL
# Products in a category
-curl 'https://api.mystore.com/api/v3/store/taxons/categories/clothing/products?limit=12' \
+curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
-H 'Authorization: Bearer spree_pk_xxx'
-# Filter by taxon ID
-curl 'https://api.mystore.com/api/v3/store/products?q[taxon_id_eq]=txn_xxx' \
+# Filter by category ID
+curl 'https://api.mystore.com/api/v3/store/products?q[categories_id_eq]=ctg_xxx' \
-H 'Authorization: Bearer spree_pk_xxx'
```
@@ -138,7 +138,7 @@ curl 'https://api.mystore.com/api/v3/store/products?sort=price_low_to_high' \
## Product Filters (Faceted Search)
-Get available filter options for building a faceted search UI. Returns option values, price ranges, and taxons with counts:
+Get available filter options for building a faceted search UI. Returns option values, price ranges, and categories with counts:
<CodeGroup>
@@ -147,12 +147,12 @@ const filters = await client.products.filters()
// {
// option_types: [{ name: "size", option_values: [{ name: "Small", count: 12 }, ...] }],
// price_range: { min: 9.99, max: 199.99 },
-// taxons: [{ id: "txn_xxx", name: "Clothing", count: 45 }],
+// categories: [{ id: "ctg_xxx", name: "Clothing", count: 45 }],
// }
// Scoped to a specific category
-const taxonFilters = await client.products.filters({
- taxon_id_eq: 'txn_xxx',
+const categoryFilters = await client.products.filters({
+ category_id: 'ctg_xxx',
})
```
@@ -161,8 +161,8 @@ const taxonFilters = await client.products.filters({
curl 'https://api.mystore.com/api/v3/store/products/filters' \
-H 'Authorization: Bearer spree_pk_xxx'
-# Scoped to a taxon
-curl 'https://api.mystore.com/api/v3/store/products/filters?taxon_id_eq=txn_xxx' \
+# Scoped to a category
+curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
-H 'Authorization: Bearer spree_pk_xxx'
```
diff --git a/docs/developer/core-concepts/slugs.mdx b/docs/developer/core-concepts/slugs.mdx
index b1876ba9b1..5028266ab7 100644
--- a/docs/developer/core-concepts/slugs.mdx
+++ b/docs/developer/core-concepts/slugs.mdx
@@ -5,7 +5,7 @@ description: SEO-friendly URL identifiers for products, categories, and other re
## Overview
-Spree generates SEO-friendly URL slugs for resources like products, taxons, and stores. Instead of accessing resources by ID, you can use clean, readable URLs based on resource names.
+Spree generates SEO-friendly URL slugs for resources like products, categories, and stores. Instead of accessing resources by ID, you can use clean, readable URLs based on resource names.
Both the Store API and Admin API accept slugs or IDs interchangeably for resource lookups.
@@ -16,8 +16,8 @@ Both the Store API and Admin API accept slugs or IDs interchangeably for resourc
const product = await client.products.get('spree-tote')
const product = await client.products.get('prod_86Rf07xd4z')
-// Taxons use permalink slugs
-const taxon = await client.taxons.get('categories/clothing')
+// Categories use permalink slugs
+const category = await client.categories.get('clothing/shirts')
```
```bash cURL
@@ -49,21 +49,21 @@ If a slug already exists, Spree appends the SKU or a unique identifier to ensure
| Resource | Slug Column | Translatable | Hierarchical |
|----------|-------------|:---:|:---:|
| Product | `slug` | Yes | No |
-| Taxon | `permalink` | Yes | Yes |
+| Category | `permalink` | Yes | Yes |
| Store | `code` | No | No |
| Post | `slug` | Yes | No |
-### Taxon Permalinks
+### Category Permalinks
-Taxon slugs include the full parent path, making them hierarchical:
+Category slugs include the full parent path, making them hierarchical:
```
-categories → "categories"
-categories/clothing → "categories/clothing"
-categories/clothing/t-shirts → "categories/clothing/t-shirts"
+clothing → "clothing"
+clothing/shirts → "clothing/shirts"
+clothing/shirts/t-shirts → "clothing/shirts/t-shirts"
```
-When a parent taxon is renamed, all child permalinks update automatically.
+When a parent category is renamed, all child permalinks update automatically.
## Slug History
@@ -75,7 +75,7 @@ When a slug changes (e.g., a product is renamed), Spree preserves the old slug.
## Internationalization
-Products, taxons, and posts support localized slugs — a different slug per locale:
+Products, categories, and posts support localized slugs — a different slug per locale:
<CodeGroup>
diff --git a/docs/developer/core-concepts/translations.mdx b/docs/developer/core-concepts/translations.mdx
index 2448f3bb5c..b70ef64d34 100644
--- a/docs/developer/core-concepts/translations.mdx
+++ b/docs/developer/core-concepts/translations.mdx
@@ -77,8 +77,8 @@ product.name // "Sac Spree"
product.description // "Un sac fourre-tout élégant..."
product.slug // "sac-spree"
-// List taxons in German
-const { data: taxons } = await client.taxons.list({}, {
+// List categories in German
+const { data: categories } = await client.categories.list({}, {
locale: 'de',
})
```
diff --git a/docs/developer/sdk/configuration.mdx b/docs/developer/sdk/configuration.mdx
index e00cce9217..5d406ad194 100644
--- a/docs/developer/sdk/configuration.mdx
+++ b/docs/developer/sdk/configuration.mdx
@@ -13,7 +13,7 @@ Pass locale and currency headers with any request. For full details, see the [Lo
```typescript
// Works with all endpoints
-const taxon = await client.taxons.get('categories/clothing', {
+const category = await client.categories.get('clothing/shirts', {
expand: ['ancestors'],
}, {
locale: 'de',
@@ -83,8 +83,7 @@ import type {
StoreProduct,
StoreOrder,
StoreVariant,
- StoreTaxon,
- StoreTaxonomy,
+ StoreCategory,
StoreLineItem,
StoreAddress,
StoreCustomer,
@@ -93,7 +92,7 @@ import type {
// All responses are fully typed
const products: PaginatedResponse<StoreProduct> = await client.products.list();
-const taxon: StoreTaxon = await client.taxons.get('clothing');
+const category: StoreCategory = await client.categories.get('clothing');
```
## Available Types
@@ -103,8 +102,7 @@ const taxon: StoreTaxon = await client.taxons.get('clothing');
- `StoreVariant` - Variant data
- `StoreOrder` - Order/cart data
- `StoreLineItem` - Line item in cart
-- `StoreTaxonomy` - Category group
-- `StoreTaxon` - Individual category
+- `StoreCategory` - Category
- `StoreCountry` - Country with states
- `StoreState` - State/province
- `StoreAddress` - Customer address
diff --git a/docs/developer/sdk/quickstart.mdx b/docs/developer/sdk/quickstart.mdx
index fa01f3a0e8..4418505203 100644
--- a/docs/developer/sdk/quickstart.mdx
+++ b/docs/developer/sdk/quickstart.mdx
@@ -68,7 +68,7 @@ The SDK uses a resource builder pattern for nested resources:
| `customer` | `giftCards` | `list`, `get` |
| `customer` | `orders` | `list` |
| `customer` | `paymentSetupSessions` | `create`, `get`, `complete` |
-| `taxons` | `products` | `list` |
+| `categories` | `products` | `list` |
| `wishlists` | `items` | `create`, `update`, `delete` |
```typescript
@@ -77,6 +77,6 @@ await client.orders.lineItems.create(orderId, params, options);
await client.orders.payments.list(orderId, options);
await client.orders.shipments.update(orderId, shipmentId, params, options);
await client.customer.addresses.list({}, options);
-await client.taxons.products.list(taxonId, params, options);
+await client.categories.products.list(categoryId, params, options);
await client.wishlists.items.create(wishlistId, params, options);
```
diff --git a/docs/developer/sdk/store/products.mdx b/docs/developer/sdk/store/products.mdx
index a06708356c..3a400f070b 100644
--- a/docs/developer/sdk/store/products.mdx
+++ b/docs/developer/sdk/store/products.mdx
@@ -1,6 +1,6 @@
---
title: Products & Categories
-description: Browse products, categories, and taxonomies with the Spree SDK
+description: Browse products and categories with the Spree SDK
---
## Products
@@ -11,7 +11,7 @@ description: Browse products, categories, and taxonomies with the Spree SDK
const products = await client.products.list({
page: 1,
limit: 25,
- expand: ['variants', 'images', 'taxons'],
+ expand: ['variants', 'images', 'categories'],
});
```
@@ -86,11 +86,11 @@ const product = await client.products.get('spree-tote', {
### Product Filters
-Get available filters (price range, availability, options, taxons) and sort options for building filter UIs:
+Get available filters (price range, availability, options, categories) and sort options for building filter UIs:
```typescript
const filters = await client.products.filters({
- taxon_id: 'txn_abc123', // Optional: scope filters to a taxon
+ category_id: 'ctg_abc123', // Optional: scope filters to a category
});
// Response:
@@ -99,7 +99,7 @@ const filters = await client.products.filters({
// { id: 'price', type: 'price_range', min: 9.99, max: 199.99, currency: 'USD' },
// { id: 'availability', type: 'availability', options: [{ id: 'in_stock', count: 42 }, ...] },
// { id: 'opttype_abc', type: 'option', name: 'color', presentation: 'Color', options: [...] },
-// { id: 'taxons', type: 'taxon', options: [{ id: 'txn_abc', name: 'Shirts', permalink: '...', count: 12 }] },
+// { id: 'categories', type: 'category', options: [{ id: 'ctg_abc', name: 'Shirts', permalink: '...', count: 12 }] },
// ],
// sort_options: [{ id: 'manual' }, { id: 'price' }, { id: 'best_selling' }, ...],
// default_sort: 'manual',
@@ -107,39 +107,22 @@ const filters = await client.products.filters({
// }
```
-## Categories (Taxonomies & Taxons)
+## Categories
-### List Taxonomies
+### List Categories
```typescript
-const taxonomies = await client.taxonomies.list({
- expand: ['taxons'],
-});
-```
-
-### Get a Taxonomy
-
-```typescript
-const categories = await client.taxonomies.get('tax_123', {
- expand: ['root', 'taxons'],
-});
-```
-
-### List Taxons
-
-```typescript
-const taxons = await client.taxons.list({
+const categories = await client.categories.list({
depth_eq: 1, // Top-level categories only
- taxonomy_id_eq: '123', // Filter by taxonomy
});
```
-### Get a Taxon
+### Get a Category
Fetch by ID or permalink:
```typescript
-const taxon = await client.taxons.get('categories/clothing', {
+const category = await client.categories.get('clothing/shirts', {
expand: ['ancestors', 'children'], // For breadcrumbs and subcategories
});
```
@@ -147,7 +130,7 @@ const taxon = await client.taxons.get('categories/clothing', {
### List Products in a Category
```typescript
-const categoryProducts = await client.taxons.products.list('categories/clothing', {
+const categoryProducts = await client.categories.products.list('clothing/shirts', {
page: 1,
limit: 12,
expand: ['images', 'default_variant'],
diff --git a/docs/developer/storefront/nextjs/architecture.mdx b/docs/developer/storefront/nextjs/architecture.mdx
index d1665b915c..db57af3577 100644
--- a/docs/developer/storefront/nextjs/architecture.mdx
+++ b/docs/developer/storefront/nextjs/architecture.mdx
@@ -36,8 +36,8 @@ src/
│ │ ├── cart/ # Shopping cart
│ │ ├── products/ # Product listing
│ │ │ └── [slug]/ # Product details
-│ │ ├── t/[...permalink]/ # Taxon/category pages
-│ │ └── taxonomies/ # Category overview
+│ │ ├── t/[...permalink]/ # Category pages
+│ │ └── categories/ # Category overview
│ └── (checkout)/ # Checkout layout (no header/footer)
│ ├── checkout/[id]/ # Checkout flow
│ └── order-placed/[id]/ # Order confirmation
@@ -72,7 +72,7 @@ src/
│ ├── payment.ts # Payment processing
│ ├── products.ts # Product queries
│ ├── store.ts # Store configuration
- │ ├── taxonomies.ts # Categories/taxons
+ │ ├── categories.ts # Categories
│ └── utils.ts # Shared helpers (actionResult, withFallback)
└── utils/ # Client utilities
├── address.ts # Address formatting
diff --git a/docs/developer/storefront/nextjs/customization.mdx b/docs/developer/storefront/nextjs/customization.mdx
index 78204b20f9..0d932abddd 100644
--- a/docs/developer/storefront/nextjs/customization.mdx
+++ b/docs/developer/storefront/nextjs/customization.mdx
@@ -103,7 +103,7 @@ To customize API behavior, modify the server actions in `src/lib/data/`. Each fi
| `addresses.ts` | Address CRUD |
| `orders.ts` | Order history |
| `payment.ts` | Payment sessions and processing |
-| `taxonomies.ts` | Categories and taxons |
+| `categories.ts` | Categories |
| `countries.ts` | Country and region data |
| `cookies.ts` | Auth check helper |
| `store.ts` | Store configuration |
diff --git a/docs/developer/storefront/nextjs/spree-next-package.mdx b/docs/developer/storefront/nextjs/spree-next-package.mdx
index 4efd91b17d..81a2579dcc 100644
--- a/docs/developer/storefront/nextjs/spree-next-package.mdx
+++ b/docs/developer/storefront/nextjs/spree-next-package.mdx
@@ -50,21 +50,17 @@ import { listProducts, getProduct, getProductFilters } from '@spree/next';
const products = await listProducts({ limit: 25 });
const product = await getProduct('spree-tote', { expand: ['variants', 'images'] });
-const filters = await getProductFilters({ taxon_id_eq: 'txn_123' });
+const filters = await getProductFilters({ category_id: 'ctg_123' });
```
### Categories
```typescript
-import { listTaxons, getTaxon, listTaxonProducts } from '@spree/next';
-import { listTaxonomies, getTaxonomy } from '@spree/next';
+import { listCategories, getCategory, listCategoryProducts } from '@spree/next';
-const taxons = await listTaxons({ depth_eq: 1 });
-const taxon = await getTaxon('categories/clothing');
-const products = await listTaxonProducts('categories/clothing', { limit: 12 });
-
-const taxonomies = await listTaxonomies({ expand: ['taxons'] });
-const taxonomy = await getTaxonomy('tax_123');
+const categories = await listCategories({ depth_eq: 1 });
+const category = await getCategory('clothing/shirts');
+const products = await listCategoryProducts('clothing/shirts', { limit: 12 });
```
### Store & Geography
@@ -82,11 +78,11 @@ const locales = await listLocales();
### Using in Server Components
```typescript
-import { listProducts, listTaxons } from '@spree/next';
+import { listProducts, listCategories } from '@spree/next';
export default async function ProductsPage() {
const products = await listProducts({ limit: 12 });
- const categories = await listTaxons({ depth_eq: 1 });
+ const categories = await listCategories({ depth_eq: 1 });
return (
<div>
@@ -268,7 +264,7 @@ Then data functions work without any locale arguments:
```typescript
// Locale/country auto-read from cookies — no options needed
const products = await listProducts({ limit: 10 });
-const taxon = await getTaxon('categories/clothing');
+const category = await getCategory('clothing/shirts');
```
Use the `setLocale` server action in country/language switchers:
@@ -285,7 +281,7 @@ You can still pass locale options explicitly — they override the auto-detected
```typescript
const products = await listProducts({ limit: 10 }, { locale: 'fr', country: 'FR' });
-const taxon = await getTaxon('categories/clothing', {}, { locale: 'de', country: 'DE' });
+const category = await getCategory('clothing/shirts', {}, { locale: 'de', country: 'DE' });
```
## TypeScript
@@ -298,8 +294,7 @@ import type {
StoreOrder,
StoreLineItem,
StoreVariant,
- StoreTaxon,
- StoreTaxonomy,
+ StoreCategory,
StoreCountry,
StoreCurrency,
StoreLocale,
diff --git a/packages/admin-sdk/src/types/generated/Taxon.ts b/packages/admin-sdk/src/types/generated/Category.ts
similarity index 83%
rename from packages/admin-sdk/src/types/generated/Taxon.ts
rename to packages/admin-sdk/src/types/generated/Category.ts
index 60893b6eb4..e23c5f49e7 100644
--- a/packages/admin-sdk/src/types/generated/Taxon.ts
+++ b/packages/admin-sdk/src/types/generated/Category.ts
@@ -3,7 +3,7 @@
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Metafield} from '@/types'
-type Taxon = {
+type Category = {
id: string;
name: string;
permalink: string;
@@ -16,7 +16,6 @@ type Taxon = {
created_at: string;
updated_at: string;
parent_id: string | null;
- taxonomy_id: string;
description: string;
description_html: string;
image_url: string | null;
@@ -24,12 +23,12 @@ type Taxon = {
is_root: boolean;
is_child: boolean;
is_leaf: boolean;
- parent?: Taxon;
- children?: Array<Taxon>;
- ancestors?: Array<Taxon>;
+ parent?: Category;
+ children?: Array<Category>;
+ ancestors?: Array<Category>;
metafields?: Array<Metafield>;
lft: number;
rgt: number;
}
-export default Taxon;
+export default Category;
diff --git a/packages/admin-sdk/src/types/generated/Product.ts b/packages/admin-sdk/src/types/generated/Product.ts
index 715599968d..9ca6675632 100644
--- a/packages/admin-sdk/src/types/generated/Product.ts
+++ b/packages/admin-sdk/src/types/generated/Product.ts
@@ -1,7 +1,7 @@
// Typelizer digest 645a2f6c5a8bc5e6d7aa115ed2613816
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {Price, Image, Variant, OptionType, Taxon, Metafield} from '@/types'
+import type {Price, Image, Variant, OptionType, Category, Metafield} from '@/types'
type Product = {
id: string;
@@ -28,7 +28,7 @@ type Product = {
default_variant?: Variant;
master_variant?: Variant;
option_types?: Array<OptionType>;
- taxons?: Array<Taxon>;
+ categories?: Array<Category>;
metafields?: Array<Metafield>;
status: string;
make_active_at: string | null;
diff --git a/packages/admin-sdk/src/types/generated/Taxonomy.ts b/packages/admin-sdk/src/types/generated/Taxonomy.ts
deleted file mode 100644
index 0a7cc3bb0d..0000000000
--- a/packages/admin-sdk/src/types/generated/Taxonomy.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-// Typelizer digest 025489f61da85aa52eca12992b09d2c1
-//
-// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {Taxon, Metafield} from '@/types'
-
-type Taxonomy = {
- id: string;
- name: string;
- position: number;
- created_at: string;
- updated_at: string;
- root_id: string | null;
- root?: Taxon;
- taxons?: Array<Taxon>;
- metafields?: Array<Metafield>;
-}
-
-export default Taxonomy;
diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.ts
index ddf3f1da16..f2841e6687 100644
--- a/packages/admin-sdk/src/types/generated/index.ts
+++ b/packages/admin-sdk/src/types/generated/index.ts
@@ -5,6 +5,7 @@ export type { default as Address } from './Address'
export type { default as Adjustment } from './Adjustment'
export type { default as AdminUser } from './AdminUser'
export type { default as Asset } from './Asset'
+export type { default as Category } from './Category'
export type { default as CreditCard } from './CreditCard'
export type { default as Customer } from './Customer'
export type { default as DigitalLink } from './DigitalLink'
@@ -31,6 +32,4 @@ export type { default as StockItem } from './StockItem'
export type { default as StockLocation } from './StockLocation'
export type { default as StoreCredit } from './StoreCredit'
export type { default as TaxCategory } from './TaxCategory'
-export type { default as Taxon } from './Taxon'
-export type { default as Taxonomy } from './Taxonomy'
export type { default as Variant } from './Variant'
diff --git a/packages/next/.changeset/rename-taxons-to-categories.md b/packages/next/.changeset/rename-taxons-to-categories.md
new file mode 100644
index 0000000000..ced09b0c7e
--- /dev/null
+++ b/packages/next/.changeset/rename-taxons-to-categories.md
@@ -0,0 +1,5 @@
+---
+"@spree/next": patch
+---
+
+Renamed Taxons/Taxonomies to Categories. `listTaxons`/`getTaxon`/`listTaxonProducts` replaced with `listCategories`/`getCategory`/`listCategoryProducts`. `listTaxonomies`/`getTaxonomy` removed. Re-exported `Category` type replaces `Taxon`/`Taxonomy`.
diff --git a/packages/next/CHANGELOG.md b/packages/next/CHANGELOG.md
index ab09f5ddd2..d3f328fb73 100644
--- a/packages/next/CHANGELOG.md
+++ b/packages/next/CHANGELOG.md
@@ -1,5 +1,11 @@
# @spree/next
+## 0.8.1
+
+### Patch Changes
+
+- Renamed Taxons/Taxonomies to Categories. `listTaxons`/`getTaxon`/`listTaxonProducts` replaced with `listCategories`/`getCategory`/`listCategoryProducts`. `listTaxonomies`/`getTaxonomy` removed. Re-exported `Category` type replaces `Taxon`/`Taxonomy`.
+
## 0.8.0
### Minor Changes
diff --git a/packages/next/README.md b/packages/next/README.md
index f586867f55..9ea285ff9e 100644
--- a/packages/next/README.md
+++ b/packages/next/README.md
@@ -36,11 +36,11 @@ initSpreeNext({
### 2. Fetch data in Server Components
```typescript
-import { listProducts, getProduct, listTaxons } from '@spree/next';
+import { listProducts, getProduct, listCategories } from '@spree/next';
export default async function ProductsPage() {
const products = await listProducts({ limit: 12 });
- const categories = await listTaxons({ depth_eq: 1 });
+ const categories = await listCategories({ depth_eq: 1 });
return (
<div>
@@ -95,21 +95,17 @@ import { listProducts, getProduct, getProductFilters } from '@spree/next';
const products = await listProducts({ limit: 25, expand: ['variants', 'images'] });
const product = await getProduct('spree-tote');
-const filters = await getProductFilters({ taxon_id: 'txn_123' });
+const filters = await getProductFilters({ category_id: 'ctg_123' });
```
### Categories
```typescript
-import { listTaxons, getTaxon, listTaxonProducts } from '@spree/next';
-import { listTaxonomies, getTaxonomy } from '@spree/next';
+import { listCategories, getCategory, listCategoryProducts } from '@spree/next';
-const taxons = await listTaxons({ depth_eq: 1 });
-const taxon = await getTaxon('categories/clothing');
-const products = await listTaxonProducts('categories/clothing', { limit: 12 });
-
-const taxonomies = await listTaxonomies({ expand: ['taxons'] });
-const taxonomy = await getTaxonomy('tax_123');
+const categories = await listCategories({ depth_eq: 1 });
+const category = await getCategory('clothing/shirts');
+const products = await listCategoryProducts('clothing/shirts', { limit: 12 });
```
### Store & Geography
@@ -262,7 +258,7 @@ Data functions work without any locale arguments:
```typescript
const products = await listProducts({ limit: 10 });
-const taxon = await getTaxon('categories/clothing');
+const category = await getCategory('clothing/shirts');
```
Use the `setLocale` server action in country/language switchers:
@@ -291,7 +287,7 @@ import type {
StoreOrder,
StoreLineItem,
StorePaymentSession,
- StoreTaxon,
+ StoreCategory,
PaginatedResponse,
SpreeError,
} from '@spree/next';
diff --git a/packages/next/package.json b/packages/next/package.json
index 0fde06ee0b..79bdfe1f46 100644
--- a/packages/next/package.json
+++ b/packages/next/package.json
@@ -1,6 +1,6 @@
{
"name": "@spree/next",
- "version": "0.8.0",
+ "version": "0.8.1",
"description": "Next.js integration for Spree Commerce — server actions, caching, and cookie-based auth",
"type": "module",
"main": "./dist/index.js",
@@ -62,7 +62,7 @@
"url": "https://github.com/spree/spree/issues"
},
"peerDependencies": {
- "@spree/sdk": ">=0.8.0",
+ "@spree/sdk": ">=0.8.1",
"next": ">=15.0.0",
"react": ">=19.0.0"
},
diff --git a/packages/next/src/data/taxons.ts b/packages/next/src/data/categories.ts
similarity index 52%
rename from packages/next/src/data/taxons.ts
rename to packages/next/src/data/categories.ts
index db24d9d961..2924d38c17 100644
--- a/packages/next/src/data/taxons.ts
+++ b/packages/next/src/data/categories.ts
@@ -1,42 +1,42 @@
-import type { Taxon, Product, PaginatedResponse, TaxonListParams, ProductListParams } from '@spree/sdk';
+import type { Category, Product, PaginatedResponse, CategoryListParams, ProductListParams } from '@spree/sdk';
import { getClient } from '../config';
import { getLocaleOptions } from '../locale';
import type { SpreeNextOptions } from '../types';
/**
- * List taxons (categories) with optional filtering and pagination.
+ * List categories with optional filtering and pagination.
* Locale/country are auto-read from cookies when not provided.
*/
-export async function listTaxons(
- params?: TaxonListParams,
+export async function listCategories(
+ params?: CategoryListParams,
options?: SpreeNextOptions
-): Promise<PaginatedResponse<Taxon>> {
+): Promise<PaginatedResponse<Category>> {
const resolved = options ?? await getLocaleOptions();
- return getClient().taxons.list(params, resolved);
+ return getClient().categories.list(params, resolved);
}
/**
- * Get a single taxon by ID or permalink.
+ * Get a single category by ID or permalink.
* Locale/country are auto-read from cookies when not provided.
*/
-export async function getTaxon(
+export async function getCategory(
idOrPermalink: string,
params?: Record<string, unknown>,
options?: SpreeNextOptions
-): Promise<Taxon> {
+): Promise<Category> {
const resolved = options ?? await getLocaleOptions();
- return getClient().taxons.get(idOrPermalink, params, resolved);
+ return getClient().categories.get(idOrPermalink, params, resolved);
}
/**
- * List products within a taxon.
+ * List products within a category.
* Locale/country are auto-read from cookies when not provided.
*/
-export async function listTaxonProducts(
- taxonId: string,
+export async function listCategoryProducts(
+ categoryId: string,
params?: ProductListParams,
options?: SpreeNextOptions
): Promise<PaginatedResponse<Product>> {
const resolved = options ?? await getLocaleOptions();
- return getClient().taxons.products.list(taxonId, params, resolved);
+ return getClient().categories.products.list(categoryId, params, resolved);
}
diff --git a/packages/next/src/data/taxonomies.ts b/packages/next/src/data/taxonomies.ts
deleted file mode 100644
index 2220b9348e..0000000000
--- a/packages/next/src/data/taxonomies.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import type { Taxonomy, PaginatedResponse } from '@spree/sdk';
-import { getClient } from '../config';
-import { getLocaleOptions } from '../locale';
-import type { SpreeNextOptions } from '../types';
-
-/**
- * List taxonomies with optional filtering and pagination.
- * Locale/country are auto-read from cookies when not provided.
- */
-export async function listTaxonomies(
- params?: Record<string, unknown>,
- options?: SpreeNextOptions
-): Promise<PaginatedResponse<Taxonomy>> {
- const resolved = options ?? await getLocaleOptions();
- return getClient().taxonomies.list(params, resolved);
-}
-
-/**
- * Get a single taxonomy by ID.
- * Locale/country are auto-read from cookies when not provided.
- */
-export async function getTaxonomy(
- id: string,
- params?: Record<string, unknown>,
- options?: SpreeNextOptions
-): Promise<Taxonomy> {
- const resolved = options ?? await getLocaleOptions();
- return getClient().taxonomies.get(id, params, resolved);
-}
diff --git a/packages/next/src/index.ts b/packages/next/src/index.ts
index e1fd1135de..9e3be7c3ea 100644
--- a/packages/next/src/index.ts
+++ b/packages/next/src/index.ts
@@ -4,8 +4,7 @@ export type { SpreeNextConfig, SpreeNextOptions } from './types';
// Data reads (plain async functions — wrap with "use cache" in your app)
export { listProducts, getProduct, getProductFilters } from './data/products';
-export { listTaxons, getTaxon, listTaxonProducts } from './data/taxons';
-export { listTaxonomies, getTaxonomy } from './data/taxonomies';
+export { listCategories, getCategory, listCategoryProducts } from './data/categories';
export { listCountries, getCountry } from './data/countries';
export { listCurrencies } from './data/currencies';
export { listLocales } from './data/locales';
@@ -74,8 +73,7 @@ export type {
Order,
LineItem,
Variant,
- Taxon,
- Taxonomy,
+ Category,
Country,
Currency,
Locale,
diff --git a/packages/next/tsup.config.ts b/packages/next/tsup.config.ts
index 3f535c005a..93e50a80e6 100644
--- a/packages/next/tsup.config.ts
+++ b/packages/next/tsup.config.ts
@@ -9,8 +9,7 @@ export default defineConfig([
types: 'src/types.ts',
locale: 'src/locale.ts',
'data/products': 'src/data/products.ts',
- 'data/taxons': 'src/data/taxons.ts',
- 'data/taxonomies': 'src/data/taxonomies.ts',
+ 'data/categories': 'src/data/categories.ts',
'data/countries': 'src/data/countries.ts',
'data/currencies': 'src/data/currencies.ts',
'data/locales': 'src/data/locales.ts',
diff --git a/packages/sdk/.changeset/rename-taxons-to-categories.md b/packages/sdk/.changeset/rename-taxons-to-categories.md
new file mode 100644
index 0000000000..40383391a1
--- /dev/null
+++ b/packages/sdk/.changeset/rename-taxons-to-categories.md
@@ -0,0 +1,5 @@
+---
+"@spree/sdk": patch
+---
+
+Renamed Taxons/Taxonomies to Categories in the public API surface. `client.taxons` is now `client.categories`, `client.taxonomies` has been removed. Types `Taxon`/`Taxonomy` replaced with `Category`. Filter types updated accordingly (`TaxonFilter` → `CategoryFilter`, `TaxonListParams` → `CategoryListParams`, `ProductFiltersParams.taxon_id` → `category_id`).
diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.md
index 20943f3063..28885ab892 100644
--- a/packages/sdk/CHANGELOG.md
+++ b/packages/sdk/CHANGELOG.md
@@ -1,5 +1,11 @@
# @spree/sdk
+## 0.8.1
+
+### Patch Changes
+
+- Renamed Taxons/Taxonomies to Categories in the public API surface. `client.taxons` is now `client.categories`, `client.taxonomies` has been removed. Types `Taxon`/`Taxonomy` replaced with `Category`. Filter types updated accordingly (`TaxonFilter` → `CategoryFilter`, `TaxonListParams` → `CategoryListParams`, `ProductFiltersParams.taxon_id` → `category_id`).
+
## 0.8.0
### Minor Changes
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index 8c45afc014..9ec094aecd 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -150,7 +150,7 @@ const products = await client.products.list({
limit: 25,
name_cont: 'shirt',
sort: 'price asc',
- expand: ['variants', 'images', 'taxons'],
+ expand: ['variants', 'images', 'categories'],
});
// Get single product by ID or slug
@@ -158,38 +158,27 @@ const product = await client.products.get('spree-tote', {
expand: ['variants', 'images'],
});
-// Get available filters (price range, availability, options, taxons)
+// Get available filters (price range, availability, options, categories)
const filters = await client.products.filters({
- taxon_id: 'txn_abc123', // Optional: scope filters to a taxon
+ category_id: 'ctg_abc123', // Optional: scope filters to a category
});
```
-### Categories (Taxonomies & Taxons)
+### Categories
```typescript
-// List taxonomies
-const taxonomies = await client.taxonomies.list({
- expand: ['taxons'],
-});
-
-// Get taxonomy with taxons
-const categories = await client.taxonomies.get('tax_123', {
- expand: ['root', 'taxons'],
-});
-
-// List taxons with filtering
-const taxons = await client.taxons.list({
+// List categories with filtering
+const categories = await client.categories.list({
depth_eq: 1, // Top-level categories only
- taxonomy_id_eq: '123', // Filter by taxonomy
});
-// Get single taxon by ID or permalink
-const taxon = await client.taxons.get('categories/clothing', {
+// Get single category by ID or permalink
+const category = await client.categories.get('clothing/shirts', {
expand: ['ancestors', 'children'], // For breadcrumbs and subcategories
});
// List products in a category
-const categoryProducts = await client.taxons.products.list('categories/clothing', {
+const categoryProducts = await client.categories.products.list('clothing/shirts', {
page: 1,
limit: 12,
expand: ['images', 'default_variant'],
@@ -525,7 +514,7 @@ The SDK uses a resource builder pattern for nested resources:
| `customer` | `creditCards` | `list`, `get`, `delete` |
| `customer` | `giftCards` | `list`, `get` |
| `markets` | `countries` | `list`, `get` |
-| `taxons` | `products` | `list` |
+| `categories` | `products` | `list` |
| `wishlists` | `items` | `create`, `update`, `delete` |
Example:
@@ -536,7 +525,7 @@ await client.orders.payments.list(orderId, options);
await client.orders.shipments.update(orderId, shipmentId, params, options);
await client.customer.addresses.list({}, options);
await client.markets.countries.list(marketId);
-await client.taxons.products.list(taxonId, params, options);
+await client.categories.products.list(categoryId, params, options);
await client.wishlists.items.create(wishlistId, params, options);
```
@@ -605,8 +594,7 @@ import type {
StoreProduct,
StoreOrder,
StoreVariant,
- StoreTaxon,
- StoreTaxonomy,
+ StoreCategory,
StoreLineItem,
StoreAddress,
StoreCustomer,
@@ -615,7 +603,7 @@ import type {
// All responses are fully typed
const products: PaginatedResponse<StoreProduct> = await client.products.list();
-const taxon: StoreTaxon = await client.taxons.get('clothing');
+const category: StoreCategory = await client.categories.get('clothing');
```
## Available Types
@@ -627,8 +615,7 @@ The SDK exports all Store API types:
- `StoreVariant` - Variant data
- `StoreOrder` - Order/cart data
- `StoreLineItem` - Line item in cart
-- `StoreTaxonomy` - Category group
-- `StoreTaxon` - Individual category
+- `StoreCategory` - Category
- `StoreCountry` - Country with states
- `StoreState` - State/province
- `StoreAddress` - Customer address
diff --git a/packages/sdk/console.ts b/packages/sdk/console.ts
index fb16fa0a32..150048926e 100644
--- a/packages/sdk/console.ts
+++ b/packages/sdk/console.ts
@@ -25,7 +25,7 @@ console.log("Examples:");
console.log(" await client.products.list()");
console.log(' await client.products.get("my-product", {}, { locale: "fr" })');
console.log(
- ' await client.taxons.get("categories/clothing", {}, { currency: "EUR" })',
+ ' await client.categories.get("clothing/shirts", {}, { currency: "EUR" })',
);
console.log("");
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 0cd0c85277..6302c9d60e 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -1,6 +1,6 @@
{
"name": "@spree/sdk",
- "version": "0.8.0",
+ "version": "0.8.1",
"description": "Official TypeScript SDK for Spree Commerce Store API",
"type": "module",
"main": "./dist/index.cjs",
diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.ts
index 097f8dba4e..093d4edfea 100644
--- a/packages/sdk/src/store-client.ts
+++ b/packages/sdk/src/store-client.ts
@@ -13,7 +13,7 @@ import type {
ProductListParams,
ProductFiltersParams,
ProductFiltersResponse,
- TaxonListParams,
+ CategoryListParams,
OrderListParams,
CreateCartParams,
AddLineItemParams,
@@ -32,8 +32,7 @@ import type {
Currency,
Locale,
Market,
- Taxonomy,
- Taxon,
+ Category,
Payment,
PaymentMethod,
PaymentSession,
@@ -102,7 +101,7 @@ export class StoreClient {
/**
* Get available filters for products
- * Returns filter options (price range, availability, option types, taxons) with counts
+ * Returns filter options (price range, availability, option types, categories) with counts
*/
filters: (
params?: ProductFiltersParams,
@@ -115,78 +114,51 @@ export class StoreClient {
};
// ============================================
- // Taxonomies & Taxons
+ // Categories
// ============================================
- readonly taxonomies = {
+ readonly categories = {
/**
- * List taxonomies
+ * List categories
*/
list: (
- params?: ListParams,
- options?: RequestOptions
- ): Promise<PaginatedResponse<Taxonomy>> =>
- this.request<PaginatedResponse<Taxonomy>>('GET', '/taxonomies', {
- ...options,
- params: transformListParams({ ...params }),
- }),
-
- /**
- * Get a taxonomy by ID
- */
- get: (
- id: string,
- params?: { expand?: string[]; fields?: string[] },
- options?: RequestOptions
- ): Promise<Taxonomy> =>
- this.request<Taxonomy>('GET', `/taxonomies/${id}`, {
- ...options,
- params: getParams(params),
- }),
- };
-
- readonly taxons = {
- /**
- * List taxons
- */
- list: (
- params?: TaxonListParams,
+ params?: CategoryListParams,
options?: RequestOptions
- ): Promise<PaginatedResponse<Taxon>> =>
- this.request<PaginatedResponse<Taxon>>('GET', '/taxons', {
+ ): Promise<PaginatedResponse<Category>> =>
+ this.request<PaginatedResponse<Category>>('GET', '/categories', {
...options,
params: transformListParams({ ...params }),
}),
/**
- * Get a taxon by ID or permalink
+ * Get a category by ID or permalink
*/
get: (
idOrPermalink: string,
params?: { expand?: string[]; fields?: string[] },
options?: RequestOptions
- ): Promise<Taxon> =>
- this.request<Taxon>('GET', `/taxons/${idOrPermalink}`, {
+ ): Promise<Category> =>
+ this.request<Category>('GET', `/categories/${idOrPermalink}`, {
...options,
params: getParams(params),
}),
/**
- * Nested resource: Products in a taxon
+ * Nested resource: Products in a category
*/
products: {
/**
- * List products in a taxon
- * @param taxonId - Taxon ID (prefix_id) or permalink
+ * List products in a category
+ * @param categoryId - Category ID (prefix_id) or permalink
*/
list: (
- taxonId: string,
+ categoryId: string,
params?: ProductListParams,
options?: RequestOptions
): Promise<PaginatedResponse<Product>> =>
this.request<PaginatedResponse<Product>>(
'GET',
- `/taxons/${taxonId}/products`,
+ `/categories/${categoryId}/products`,
{
...options,
params: transformListParams({ ...params }),
diff --git a/packages/sdk/src/types/generated/Taxon.ts b/packages/sdk/src/types/generated/Category.ts
similarity index 83%
rename from packages/sdk/src/types/generated/Taxon.ts
rename to packages/sdk/src/types/generated/Category.ts
index 21c4aafbc5..a812ee3f9d 100644
--- a/packages/sdk/src/types/generated/Taxon.ts
+++ b/packages/sdk/src/types/generated/Category.ts
@@ -3,7 +3,7 @@
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Metafield} from '@/types'
-type Taxon = {
+type Category = {
id: string;
name: string;
permalink: string;
@@ -16,7 +16,6 @@ type Taxon = {
created_at: string;
updated_at: string;
parent_id: string | null;
- taxonomy_id: string;
description: string;
description_html: string;
image_url: string | null;
@@ -24,10 +23,10 @@ type Taxon = {
is_root: boolean;
is_child: boolean;
is_leaf: boolean;
- parent?: Taxon;
- children?: Array<Taxon>;
- ancestors?: Array<Taxon>;
+ parent?: Category;
+ children?: Array<Category>;
+ ancestors?: Array<Category>;
metafields?: Array<Metafield>;
}
-export default Taxon;
+export default Category;
diff --git a/packages/sdk/src/types/generated/Product.ts b/packages/sdk/src/types/generated/Product.ts
index f412d522d9..18441f363a 100644
--- a/packages/sdk/src/types/generated/Product.ts
+++ b/packages/sdk/src/types/generated/Product.ts
@@ -1,7 +1,7 @@
// Typelizer digest f9a8a140f08fdd17935cce9e01ba77cd
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {Price, Image, Variant, OptionType, Taxon, Metafield} from '@/types'
+import type {Price, Image, Variant, OptionType, Category, Metafield} from '@/types'
type Product = {
id: string;
@@ -28,7 +28,7 @@ type Product = {
default_variant?: Variant;
master_variant?: Variant;
option_types?: Array<OptionType>;
- taxons?: Array<Taxon>;
+ categories?: Array<Category>;
metafields?: Array<Metafield>;
}
diff --git a/packages/sdk/src/types/generated/Taxonomy.ts b/packages/sdk/src/types/generated/Taxonomy.ts
deleted file mode 100644
index 749c8bd84c..0000000000
--- a/packages/sdk/src/types/generated/Taxonomy.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-// Typelizer digest 0cae4f58a0a422abaae9e045425d8151
-//
-// DO NOT MODIFY: This file was automatically generated by Typelizer.
-import type {Taxon, Metafield} from '@/types'
-
-type Taxonomy = {
- id: string;
- name: string;
- position: number;
- created_at: string;
- updated_at: string;
- root_id: string | null;
- root?: Taxon;
- taxons?: Array<Taxon>;
- metafields?: Array<Metafield>;
-}
-
-export default Taxonomy;
diff --git a/packages/sdk/src/types/generated/index.ts b/packages/sdk/src/types/generated/index.ts
index 50b9e7837a..99d0e38e55 100644
--- a/packages/sdk/src/types/generated/index.ts
+++ b/packages/sdk/src/types/generated/index.ts
@@ -4,6 +4,7 @@
export type { default as Address } from './Address'
export type { default as Asset } from './Asset'
export type { default as Base } from './Base'
+export type { default as Category } from './Category'
export type { default as Country } from './Country'
export type { default as CreditCard } from './CreditCard'
export type { default as Currency } from './Currency'
@@ -51,8 +52,6 @@ export type { default as StockMovement } from './StockMovement'
export type { default as StockTransfer } from './StockTransfer'
export type { default as StoreCredit } from './StoreCredit'
export type { default as TaxCategory } from './TaxCategory'
-export type { default as Taxon } from './Taxon'
-export type { default as Taxonomy } from './Taxonomy'
export type { default as Variant } from './Variant'
export type { default as WishedItem } from './WishedItem'
export type { default as Wishlist } from './Wishlist'
diff --git a/packages/sdk/src/types/index.ts b/packages/sdk/src/types/index.ts
index c0c89e70f5..aeacfe075d 100644
--- a/packages/sdk/src/types/index.ts
+++ b/packages/sdk/src/types/index.ts
@@ -5,6 +5,7 @@ export type {
Address,
Asset,
Base,
+ Category,
Country,
CreditCard,
Currency,
@@ -52,8 +53,6 @@ export type {
StockTransfer,
StoreCredit,
TaxCategory,
- Taxon,
- Taxonomy,
Variant,
WishedItem,
Wishlist,
@@ -62,6 +61,7 @@ export type {
// Backward compatibility aliases (Store* prefix)
export type { Address as StoreAddress } from './generated';
export type { Asset as StoreAsset } from './generated';
+export type { Category as StoreCategory } from './generated';
export type { Country as StoreCountry } from './generated';
export type { CreditCard as StoreCreditCard } from './generated';
export type { Currency as StoreCurrency } from './generated';
@@ -101,8 +101,6 @@ export type { StockItem as StoreStockItem } from './generated';
export type { StockLocation as StoreStockLocation } from './generated';
export type { StoreCredit as StoreStoreCredit } from './generated';
export type { TaxCategory as StoreTaxCategory } from './generated';
-export type { Taxon as StoreTaxon } from './generated';
-export type { Taxonomy as StoreTaxonomy } from './generated';
export type { Variant as StoreVariant } from './generated';
export type { WishedItem as StoreWishedItem } from './generated';
export type { Wishlist as StoreWishlist } from './generated';
@@ -163,18 +161,17 @@ export interface ProductListParams extends ListParams {
in_stock?: boolean;
/** Filter: only out-of-stock products */
out_of_stock?: boolean;
- /** Filter: products in taxon */
- taxons_id_eq?: string;
+ /** Filter: products in category */
+ categories_id_eq?: string;
/** Any additional Ransack predicate */
[key: string]: string | number | boolean | (string | number)[] | undefined;
}
-export interface TaxonListParams extends ListParams {
+export interface CategoryListParams extends ListParams {
/** Sort order, e.g. 'name', '-created_at' */
sort?: string;
/** Filter: name contains */
name_cont?: string;
- taxonomy_id_eq?: string | number;
parent_id_eq?: string | number;
depth_eq?: number;
/** Any additional Ransack predicate */
@@ -282,7 +279,7 @@ export interface OptionFilterOption extends FilterOption {
position: number;
}
-export interface TaxonFilterOption {
+export interface CategoryFilterOption {
id: string;
name: string;
permalink: string;
@@ -311,13 +308,13 @@ export interface OptionFilter {
options: OptionFilterOption[];
}
-export interface TaxonFilter {
- id: 'taxons';
- type: 'taxon';
- options: TaxonFilterOption[];
+export interface CategoryFilter {
+ id: 'categories';
+ type: 'category';
+ options: CategoryFilterOption[];
}
-export type ProductFilter = PriceRangeFilter | AvailabilityFilter | OptionFilter | TaxonFilter;
+export type ProductFilter = PriceRangeFilter | AvailabilityFilter | OptionFilter | CategoryFilter;
export interface SortOption {
id: string;
@@ -331,6 +328,6 @@ export interface ProductFiltersResponse {
}
export interface ProductFiltersParams {
- taxon_id?: string;
+ category_id?: string;
q?: Record<string, unknown>;
}
diff --git a/packages/sdk/src/zod/generated/Taxon.ts b/packages/sdk/src/zod/generated/Category.ts
similarity index 71%
rename from packages/sdk/src/zod/generated/Taxon.ts
rename to packages/sdk/src/zod/generated/Category.ts
index ef04eb5140..e3152340f9 100644
--- a/packages/sdk/src/zod/generated/Taxon.ts
+++ b/packages/sdk/src/zod/generated/Category.ts
@@ -2,7 +2,7 @@
import { z } from 'zod';
import { MetafieldSchema } from './Metafield';
-export const TaxonSchema: z.ZodObject<any> = z.object({
+export const CategorySchema: z.ZodObject<any> = z.object({
id: z.string(),
name: z.string(),
permalink: z.string(),
@@ -15,7 +15,6 @@ export const TaxonSchema: z.ZodObject<any> = z.object({
created_at: z.string(),
updated_at: z.string(),
parent_id: z.string().nullable(),
- taxonomy_id: z.string(),
description: z.string(),
description_html: z.string(),
image_url: z.string().nullable(),
@@ -23,10 +22,10 @@ export const TaxonSchema: z.ZodObject<any> = z.object({
is_root: z.boolean(),
is_child: z.boolean(),
is_leaf: z.boolean(),
- parent: z.lazy(() => TaxonSchema).optional(),
- children: z.array(z.lazy(() => TaxonSchema)).optional(),
- ancestors: z.array(z.lazy(() => TaxonSchema)).optional(),
+ parent: z.lazy(() => CategorySchema).optional(),
+ children: z.array(z.lazy(() => CategorySchema)).optional(),
+ ancestors: z.array(z.lazy(() => CategorySchema)).optional(),
metafields: z.array(MetafieldSchema).optional(),
});
-export type Taxon = z.infer<typeof TaxonSchema>;
+export type Category = z.infer<typeof CategorySchema>;
diff --git a/packages/sdk/src/zod/generated/Product.ts b/packages/sdk/src/zod/generated/Product.ts
index 8de0e3fd13..a2b3018472 100644
--- a/packages/sdk/src/zod/generated/Product.ts
+++ b/packages/sdk/src/zod/generated/Product.ts
@@ -1,10 +1,10 @@
// This file is auto-generated. Do not edit directly.
import { z } from 'zod';
+import { CategorySchema } from './Category';
import { ImageSchema } from './Image';
import { MetafieldSchema } from './Metafield';
import { OptionTypeSchema } from './OptionType';
import { PriceSchema } from './Price';
-import { TaxonSchema } from './Taxon';
import { VariantSchema } from './Variant';
export const ProductSchema = z.object({
@@ -32,7 +32,7 @@ export const ProductSchema = z.object({
default_variant: VariantSchema.optional(),
master_variant: VariantSchema.optional(),
option_types: z.array(OptionTypeSchema).optional(),
- taxons: z.array(z.lazy(() => TaxonSchema)).optional(),
+ categories: z.array(z.lazy(() => CategorySchema)).optional(),
metafields: z.array(MetafieldSchema).optional(),
});
diff --git a/packages/sdk/src/zod/generated/Taxonomy.ts b/packages/sdk/src/zod/generated/Taxonomy.ts
deleted file mode 100644
index 571ec03d17..0000000000
--- a/packages/sdk/src/zod/generated/Taxonomy.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-// This file is auto-generated. Do not edit directly.
-import { z } from 'zod';
-import { MetafieldSchema } from './Metafield';
-import { TaxonSchema } from './Taxon';
-
-export const TaxonomySchema = z.object({
- id: z.string(),
- name: z.string(),
- position: z.number(),
- created_at: z.string(),
- updated_at: z.string(),
- root_id: z.string().nullable(),
- root: z.lazy(() => TaxonSchema).optional(),
- taxons: z.array(z.lazy(() => TaxonSchema)).optional(),
- metafields: z.array(MetafieldSchema).optional(),
-});
-
-export type Taxonomy = z.infer<typeof TaxonomySchema>;
diff --git a/packages/sdk/src/zod/generated/index.ts b/packages/sdk/src/zod/generated/index.ts
index 06ec33e33f..3bccd82243 100644
--- a/packages/sdk/src/zod/generated/index.ts
+++ b/packages/sdk/src/zod/generated/index.ts
@@ -2,6 +2,7 @@
export { AddressSchema, type Address } from './Address';
export { AssetSchema, type Asset } from './Asset';
export { BaseSchema, type Base } from './Base';
+export { CategorySchema, type Category } from './Category';
export { CountrySchema, type Country } from './Country';
export { CreditCardSchema, type CreditCard } from './CreditCard';
export { CurrencySchema, type Currency } from './Currency';
@@ -49,8 +50,6 @@ export { StockMovementSchema, type StockMovement } from './StockMovement';
export { StockTransferSchema, type StockTransfer } from './StockTransfer';
export { StoreCreditSchema, type StoreCredit } from './StoreCredit';
export { TaxCategorySchema, type TaxCategory } from './TaxCategory';
-export { TaxonSchema, type Taxon } from './Taxon';
-export { TaxonomySchema, type Taxonomy } from './Taxonomy';
export { VariantSchema, type Variant } from './Variant';
export { WishedItemSchema, type WishedItem } from './WishedItem';
export { WishlistSchema, type Wishlist } from './Wishlist';
diff --git a/packages/sdk/tests/taxons.test.ts b/packages/sdk/tests/categories.test.ts
similarity index 52%
rename from packages/sdk/tests/taxons.test.ts
rename to packages/sdk/tests/categories.test.ts
index 910ae835e4..488999a63e 100644
--- a/packages/sdk/tests/taxons.test.ts
+++ b/packages/sdk/tests/categories.test.ts
@@ -3,38 +3,30 @@ import { createTestClient } from './helpers';
import { fixtures } from './mocks/handlers';
import type { Client } from '../src';
-describe('taxons', () => {
+describe('categories', () => {
let client: Client;
beforeAll(() => { client = createTestClient(); });
describe('list', () => {
- it('returns paginated taxons', async () => {
- const result = await client.taxons.list();
+ it('returns paginated categories', async () => {
+ const result = await client.categories.list();
expect(result.data).toHaveLength(1);
expect(result.data[0].name).toBe('Clothing');
expect(result.meta.page).toBe(1);
});
-
- it('passes query parameters', async () => {
- const result = await client.taxons.list({
- taxonomy_id_eq: 'tax_1',
- });
- expect(result.data).toBeDefined();
- });
});
describe('get', () => {
- it('returns a taxon by ID', async () => {
- const result = await client.taxons.get('taxon_1');
- expect(result.name).toBe(fixtures.taxon.name);
+ it('returns a category by ID', async () => {
+ const result = await client.categories.get('ctg_1');
+ expect(result.name).toBe(fixtures.category.name);
});
-
-});
+ });
describe('products', () => {
- it('lists products in a taxon', async () => {
- const result = await client.taxons.products.list('taxon_1');
+ it('lists products in a category', async () => {
+ const result = await client.categories.products.list('ctg_1');
expect(result.data).toHaveLength(1);
expect(result.data[0].name).toBe('Test Product');
diff --git a/packages/sdk/tests/client.test.ts b/packages/sdk/tests/client.test.ts
index 203696c2ac..21c2bb118a 100644
--- a/packages/sdk/tests/client.test.ts
+++ b/packages/sdk/tests/client.test.ts
@@ -116,8 +116,7 @@ describe('createClient', () => {
expect(client.auth).toBeDefined();
expect(client.products).toBeDefined();
- expect(client.taxonomies).toBeDefined();
- expect(client.taxons).toBeDefined();
+ expect(client.categories).toBeDefined();
expect(client.countries).toBeDefined();
expect(client.currencies).toBeDefined();
expect(client.locales).toBeDefined();
diff --git a/packages/sdk/tests/mocks/handlers.ts b/packages/sdk/tests/mocks/handlers.ts
index f71815f5c0..a6ad18beef 100644
--- a/packages/sdk/tests/mocks/handlers.ts
+++ b/packages/sdk/tests/mocks/handlers.ts
@@ -48,15 +48,10 @@ export const fixtures = {
country_iso: 'US',
state_abbr: 'NY',
},
- taxonomy: {
- id: 'tax_1',
- name: 'Categories',
- position: 1,
- },
- taxon: {
- id: 'taxon_1',
+ category: {
+ id: 'ctg_1',
name: 'Clothing',
- permalink: 'categories/clothing',
+ permalink: 'clothing/shirts',
position: 1,
},
country: {
@@ -134,26 +129,17 @@ export const handlers = [
HttpResponse.json(fixtures.product)
),
- // Taxonomies
- http.get(`${API_PREFIX}/taxonomies`, () =>
- HttpResponse.json({ data: [fixtures.taxonomy], meta: paginationMeta })
- ),
-
- http.get(`${API_PREFIX}/taxonomies/:id`, () =>
- HttpResponse.json(fixtures.taxonomy)
- ),
-
- // Taxons
- http.get(`${API_PREFIX}/taxons`, () =>
- HttpResponse.json({ data: [fixtures.taxon], meta: paginationMeta })
+ // Categories
+ http.get(`${API_PREFIX}/categories`, () =>
+ HttpResponse.json({ data: [fixtures.category], meta: paginationMeta })
),
- http.get(`${API_PREFIX}/taxons/:id/products`, () =>
+ http.get(`${API_PREFIX}/categories/:id/products`, () =>
HttpResponse.json({ data: [fixtures.product], meta: paginationMeta })
),
- http.get(`${API_PREFIX}/taxons/:id`, () =>
- HttpResponse.json(fixtures.taxon)
+ http.get(`${API_PREFIX}/categories/:id`, () =>
+ HttpResponse.json(fixtures.category)
),
// Countries
diff --git a/packages/sdk/tests/params.test.ts b/packages/sdk/tests/params.test.ts
index 860bc85689..15cd0eab15 100644
--- a/packages/sdk/tests/params.test.ts
+++ b/packages/sdk/tests/params.test.ts
@@ -99,7 +99,7 @@ describe('transformListParams', () => {
sort: '-created_at',
name_cont: 'shirt',
price_gte: 20,
- taxons_id_eq: 'txn_abc123',
+ categories_id_eq: 'ctg_abc123',
});
expect(result).toEqual({
page: 1,
@@ -108,7 +108,7 @@ describe('transformListParams', () => {
sort: '-created_at',
'q[name_cont]': 'shirt',
'q[price_gte]': 20,
- 'q[taxons_id_eq]': 'txn_abc123',
+ 'q[categories_id_eq]': 'ctg_abc123',
});
});
});
diff --git a/packages/sdk/tests/taxonomies.test.ts b/packages/sdk/tests/taxonomies.test.ts
deleted file mode 100644
index e41f3442c2..0000000000
--- a/packages/sdk/tests/taxonomies.test.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { describe, it, expect, beforeAll } from 'vitest';
-import { createTestClient } from './helpers';
-import { fixtures } from './mocks/handlers';
-import type { Client } from '../src';
-
-describe('taxonomies', () => {
- let client: Client;
- beforeAll(() => { client = createTestClient(); });
-
- describe('list', () => {
- it('returns paginated taxonomies', async () => {
- const result = await client.taxonomies.list();
-
- expect(result.data).toHaveLength(1);
- expect(result.data[0].name).toBe('Categories');
- expect(result.meta.page).toBe(1);
- });
- });
-
- describe('get', () => {
- it('returns a taxonomy by ID', async () => {
- const result = await client.taxonomies.get('tax_1');
- expect(result.name).toBe(fixtures.taxonomy.name);
- });
- });
-});
diff --git a/spree/admin/spec/controllers/spree/admin/classifications_controller_spec.rb b/spree/admin/spec/controllers/spree/admin/classifications_controller_spec.rb
index bb4a8e66a9..90f66561f1 100644
--- a/spree/admin/spec/controllers/spree/admin/classifications_controller_spec.rb
+++ b/spree/admin/spec/controllers/spree/admin/classifications_controller_spec.rb
@@ -6,7 +6,8 @@ RSpec.describe Spree::Admin::ClassificationsController, type: :controller do
render_views
let(:store) { @default_store }
- let(:taxon) { create(:taxon, sort_order: sort_order, taxonomy: store.taxonomies.first) }
+ let(:taxonomy) { store.taxonomies.first || create(:taxonomy, store: store) }
+ let(:taxon) { create(:taxon, sort_order: sort_order, taxonomy: taxonomy) }
let(:sort_order) { 'manual' }
let(:product1) { create(:product, stores: [store]) }
diff --git a/spree/api/app/controllers/spree/api/v3/store/categories/products_controller.rb b/spree/api/app/controllers/spree/api/v3/store/categories/products_controller.rb
new file mode 100644
index 0000000000..1f97313b0c
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/store/categories/products_controller.rb
@@ -0,0 +1,37 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Categories
+ class ProductsController < Store::ProductsController
+ before_action :set_category
+
+ protected
+
+ def set_category
+ @category = find_category
+ end
+
+ def scope
+ super.in_category(@category)
+ end
+
+ private
+
+ def find_category
+ id = params[:category_id]
+ category_scope = Spree::Category.for_store(current_store).accessible_by(current_ability, :show)
+ category_scope = category_scope.i18n if Spree::Category.include?(Spree::TranslatableResource)
+
+ if id.to_s.start_with?('ctg_')
+ category_scope.find_by_prefix_id!(id)
+ else
+ find_with_fallback_default_locale { category_scope.i18n.find_by!(permalink: id) }
+ end
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/store/taxons_controller.rb b/spree/api/app/controllers/spree/api/v3/store/categories_controller.rb
similarity index 61%
rename from spree/api/app/controllers/spree/api/v3/store/taxons_controller.rb
rename to spree/api/app/controllers/spree/api/v3/store/categories_controller.rb
index 91a2e71265..e9332e6b17 100644
--- a/spree/api/app/controllers/spree/api/v3/store/taxons_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/categories_controller.rb
@@ -2,24 +2,24 @@ module Spree
module Api
module V3
module Store
- class TaxonsController < ResourceController
+ class CategoriesController < ResourceController
include Spree::Api::V3::HttpCaching
protected
def model_class
- Spree::Taxon
+ Spree::Category
end
def serializer_class
- Spree.api.taxon_serializer
+ Spree.api.category_serializer
end
- # Find taxon by permalink or prefixed ID with i18n scope for SEO-friendly URLs
- # Falls back to default locale if taxon is not found in the current locale
+ # Find category by permalink or prefixed ID with i18n scope for SEO-friendly URLs
+ # Falls back to default locale if category is not found in the current locale
def find_resource
id = params[:id]
- if id.to_s.start_with?('txn_')
+ if id.to_s.start_with?('ctg_')
scope.find_by_prefix_id!(id)
else
find_with_fallback_default_locale { scope.i18n.find_by!(permalink: id) }
diff --git a/spree/api/app/controllers/spree/api/v3/store/products/filters_controller.rb b/spree/api/app/controllers/spree/api/v3/store/products/filters_controller.rb
index a087e88301..4664c4df9a 100644
--- a/spree/api/app/controllers/spree/api/v3/store/products/filters_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/products/filters_controller.rb
@@ -8,27 +8,28 @@ module Spree
aggregator = Spree::Api::V3::FiltersAggregator.new(
scope: filters_scope,
currency: current_currency,
- taxon: taxon
+ category: category
)
render json: aggregator.call
end
private
- # Build scope from taxon and/or ransack params
+ # Build scope from category and/or ransack params
# @return [ActiveRecord::Relation]
def filters_scope
scope = current_store.products.active(current_currency)
- scope = scope.in_taxon(taxon) if taxon.present?
+ scope = scope.in_category(category) if category.present?
scope = scope.ransack(params[:q]).result if params[:q].present?
scope.accessible_by(current_ability, :show)
end
- # Fetches taxon from params
- # @param [String] taxon_id
- # @return [Spree::Taxon]
- def taxon
- @taxon ||= params[:taxon_id].present? ? current_store.taxons.find_by_param(params[:taxon_id]) : nil
+ # Fetches category from params
+ # @param [String] category_id
+ # @return [Spree::Category]
+ def category
+ category_id = params[:category_id]
+ @category ||= category_id.present? ? current_store.categories.find_by_param(category_id) : nil
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/store/taxonomies_controller.rb b/spree/api/app/controllers/spree/api/v3/store/taxonomies_controller.rb
deleted file mode 100644
index 83e7d1a7a3..0000000000
--- a/spree/api/app/controllers/spree/api/v3/store/taxonomies_controller.rb
+++ /dev/null
@@ -1,21 +0,0 @@
-module Spree
- module Api
- module V3
- module Store
- class TaxonomiesController < ResourceController
- include Spree::Api::V3::HttpCaching
-
- protected
-
- def model_class
- Spree::Taxonomy
- end
-
- def serializer_class
- Spree.api.taxonomy_serializer
- end
- end
- end
- end
- end
-end
diff --git a/spree/api/app/controllers/spree/api/v3/store/taxons/products_controller.rb b/spree/api/app/controllers/spree/api/v3/store/taxons/products_controller.rb
deleted file mode 100644
index f5a738bfcc..0000000000
--- a/spree/api/app/controllers/spree/api/v3/store/taxons/products_controller.rb
+++ /dev/null
@@ -1,37 +0,0 @@
-module Spree
- module Api
- module V3
- module Store
- module Taxons
- class ProductsController < Store::ProductsController
- before_action :set_taxon
-
- protected
-
- def set_taxon
- @taxon = find_taxon
- end
-
- def scope
- super.in_taxon(@taxon)
- end
-
- private
-
- def find_taxon
- id = params[:taxon_id]
- taxon_scope = Spree::Taxon.for_store(current_store).accessible_by(current_ability, :show)
- taxon_scope = taxon_scope.i18n if Spree::Taxon.include?(Spree::TranslatableResource)
-
- if id.to_s.start_with?('txn_')
- taxon_scope.find_by_prefix_id!(id)
- else
- find_with_fallback_default_locale { taxon_scope.i18n.find_by!(permalink: id) }
- end
- end
- end
- end
- end
- end
- end
-end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/taxon_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/category_serializer.rb
similarity index 66%
rename from spree/api/app/serializers/spree/api/v3/admin/taxon_serializer.rb
rename to spree/api/app/serializers/spree/api/v3/admin/category_serializer.rb
index 40e5763b6f..3f385d3ba4 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/taxon_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/category_serializer.rb
@@ -2,9 +2,9 @@ module Spree
module Api
module V3
module Admin
- # Admin API Taxon Serializer
- # Full taxon data including admin-only fields
- class TaxonSerializer < V3::TaxonSerializer
+ # Admin API Category Serializer
+ # Full category data including admin-only fields
+ class CategorySerializer < V3::CategorySerializer
typelize lft: :number, rgt: :number
# Nested set columns for tree operations
@@ -12,15 +12,15 @@ module Spree
# Override inherited associations to use admin serializers
one :parent,
- resource: Spree.api.admin_taxon_serializer,
+ resource: Spree.api.admin_category_serializer,
if: proc { expand?('parent') }
many :children,
- resource: Spree.api.admin_taxon_serializer,
+ resource: Spree.api.admin_category_serializer,
if: proc { expand?('children') }
many :ancestors,
- resource: Spree.api.admin_taxon_serializer,
+ resource: Spree.api.admin_category_serializer,
if: proc { expand?('ancestors') }
many :metafields,
diff --git a/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb
index 076b4ca587..70d86edd39 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb
@@ -50,8 +50,9 @@ module Spree
proc { |taxons, params|
taxons.select { |t| t.taxonomy.store_id == params[:store].id }
},
- resource: Spree.api.admin_taxon_serializer,
- if: proc { expand?('taxons') }
+ key: :categories,
+ resource: Spree.api.admin_category_serializer,
+ if: proc { expand?('categories') }
many :metafields,
resource: Spree.api.admin_metafield_serializer,
diff --git a/spree/api/app/serializers/spree/api/v3/admin/taxonomy_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/taxonomy_serializer.rb
deleted file mode 100644
index abc1360146..0000000000
--- a/spree/api/app/serializers/spree/api/v3/admin/taxonomy_serializer.rb
+++ /dev/null
@@ -1,24 +0,0 @@
-module Spree
- module Api
- module V3
- module Admin
- # Admin API Taxonomy Serializer
- # Full taxonomy data including admin-only fields
- class TaxonomySerializer < V3::TaxonomySerializer
- # Override inherited associations to use admin serializers
- one :root,
- resource: Spree.api.admin_taxon_serializer,
- if: proc { expand?('root') }
-
- many :taxons,
- resource: Spree.api.admin_taxon_serializer,
- if: proc { expand?('taxons') }
-
- many :metafields,
- resource: Spree.api.admin_metafield_serializer,
- if: proc { expand?('metafields') }
- end
- end
- end
- end
-end
diff --git a/spree/api/app/serializers/spree/api/v3/taxon_serializer.rb b/spree/api/app/serializers/spree/api/v3/category_serializer.rb
similarity index 55%
rename from spree/api/app/serializers/spree/api/v3/taxon_serializer.rb
rename to spree/api/app/serializers/spree/api/v3/category_serializer.rb
index 0c7a574999..d2393ca383 100644
--- a/spree/api/app/serializers/spree/api/v3/taxon_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/category_serializer.rb
@@ -1,10 +1,10 @@
module Spree
module Api
module V3
- class TaxonSerializer < BaseSerializer
+ class CategorySerializer < BaseSerializer
typelize name: :string, permalink: :string, position: :number, depth: :number,
meta_title: [:string, nullable: true], meta_description: [:string, nullable: true], meta_keywords: [:string, nullable: true],
- parent_id: [:string, nullable: true], taxonomy_id: :string, children_count: :number,
+ parent_id: [:string, nullable: true], children_count: :number,
description: :string, description_html: :string,
image_url: [:string, nullable: true], square_image_url: [:string, nullable: true],
is_root: :boolean, is_child: :boolean, is_leaf: :boolean
@@ -14,55 +14,51 @@ module Spree
:children_count,
created_at: :iso8601, updated_at: :iso8601
- attribute :parent_id do |taxon|
- taxon.parent&.prefixed_id
+ attribute :parent_id do |category|
+ category.parent&.prefixed_id
end
- attribute :taxonomy_id do |taxon|
- taxon.taxonomy&.prefixed_id
+ attribute :description do |category|
+ category.description&.to_plain_text.to_s
end
- attribute :description do |taxon|
- taxon.description&.to_plain_text.to_s
+ attribute :description_html do |category|
+ category.description&.body&.to_s.to_s
end
- attribute :description_html do |taxon|
- taxon.description&.body&.to_s.to_s
+ attribute :image_url do |category|
+ image_url_for(category.image)
end
- attribute :image_url do |taxon|
- image_url_for(taxon.image)
+ attribute :square_image_url do |category|
+ image_url_for(category.square_image)
end
- attribute :square_image_url do |taxon|
- image_url_for(taxon.square_image)
+ attribute :is_root do |category|
+ category.root?
end
- attribute :is_root do |taxon|
- taxon.root?
+ attribute :is_child do |category|
+ category.child?
end
- attribute :is_child do |taxon|
- taxon.child?
- end
-
- attribute :is_leaf do |taxon|
- taxon.leaf?
+ attribute :is_leaf do |category|
+ category.leaf?
end
# Conditional associations
- # Note: We pass empty expand to nested taxons to prevent infinite recursion
+ # Note: We pass empty expand to nested categories to prevent infinite recursion
# (e.g., ancestors trying to load their own ancestors)
one :parent,
- resource: Spree.api.taxon_serializer,
+ resource: Spree.api.category_serializer,
if: proc { expand?('parent') }
many :children,
- resource: Spree.api.taxon_serializer,
+ resource: Spree.api.category_serializer,
if: proc { expand?('children') }
many :ancestors,
- resource: Spree.api.taxon_serializer,
+ resource: Spree.api.category_serializer,
if: proc { expand?('ancestors') }
many :public_metafields,
diff --git a/spree/api/app/serializers/spree/api/v3/product_serializer.rb b/spree/api/app/serializers/spree/api/v3/product_serializer.rb
index ae9e67b997..84753f0909 100644
--- a/spree/api/app/serializers/spree/api/v3/product_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/product_serializer.rb
@@ -94,8 +94,9 @@ module Spree
proc { |taxons, params|
taxons.select { |t| t.taxonomy.store_id == params[:store].id }
},
- resource: Spree.api.taxon_serializer,
- if: proc { expand?('taxons') }
+ key: :categories,
+ resource: Spree.api.category_serializer,
+ if: proc { expand?('categories') }
many :public_metafields,
key: :metafields,
diff --git a/spree/api/app/serializers/spree/api/v3/taxonomy_serializer.rb b/spree/api/app/serializers/spree/api/v3/taxonomy_serializer.rb
deleted file mode 100644
index 5d090189f7..0000000000
--- a/spree/api/app/serializers/spree/api/v3/taxonomy_serializer.rb
+++ /dev/null
@@ -1,31 +0,0 @@
-module Spree
- module Api
- module V3
- class TaxonomySerializer < BaseSerializer
- typelize name: :string, position: :number, root_id: [:string, nullable: true]
-
- attributes :name, :position,
- created_at: :iso8601, updated_at: :iso8601
-
- attribute :root_id do |taxonomy|
- taxonomy.root&.prefixed_id
- end
-
- # Conditional associations
- # Note: We pass empty expand to nested taxons to prevent infinite recursion
- one :root,
- resource: Spree.api.taxon_serializer,
- if: proc { expand?('root') }
-
- many :taxons,
- resource: Spree.api.taxon_serializer,
- if: proc { expand?('taxons') }
-
- many :public_metafields,
- key: :metafields,
- resource: Spree.api.metafield_serializer,
- if: proc { expand?('metafields') }
- end
- end
- end
-end
diff --git a/spree/api/app/services/spree/api/v3/filters_aggregator.rb b/spree/api/app/services/spree/api/v3/filters_aggregator.rb
index 3fa8ad817a..0814abccc1 100644
--- a/spree/api/app/services/spree/api/v3/filters_aggregator.rb
+++ b/spree/api/app/services/spree/api/v3/filters_aggregator.rb
@@ -2,20 +2,20 @@ module Spree
module Api
module V3
class FiltersAggregator
- # @param scope [ActiveRecord::Relation] Base product scope (already filtered by store, availability, taxon, etc.)
+ # @param scope [ActiveRecord::Relation] Base product scope (already filtered by store, availability, category, etc.)
# @param currency [String] Currency for price range
- # @param taxon [Spree::Taxon, nil] Optional taxon for default_sort and taxon filtering context
- def initialize(scope:, currency:, taxon: nil)
+ # @param category [Spree::Category, nil] Optional category for default_sort and category filtering context
+ def initialize(scope:, currency:, category: nil)
@scope = scope
@currency = currency
- @taxon = taxon
+ @category = category
end
def call
{
filters: build_filters,
sort_options: sort_options,
- default_sort: to_api_sort(@taxon&.sort_order || 'manual'),
+ default_sort: to_api_sort(@category&.sort_order || 'manual'),
total_count: @scope.distinct.count
}
end
@@ -27,7 +27,7 @@ module Spree
price_filter,
availability_filter,
*option_type_filters,
- taxon_filter
+ category_filter
].compact
end
@@ -93,7 +93,7 @@ module Spree
def option_value_data(option_type, option_value)
# Count products in scope that have this option value
- # We use a subquery approach to avoid GROUP BY conflicts when scope includes joins (like in_taxon)
+ # We use a subquery approach to avoid GROUP BY conflicts when scope includes joins (like in_category)
# Join directly to option_value_variants for efficiency (skips joining through option_values table)
count = Spree::Product
.where(id: base_scope_product_ids)
@@ -115,31 +115,31 @@ module Spree
@base_scope_product_ids ||= @scope.reorder('').distinct.pluck(:id)
end
- def taxon_filter
- return nil if @taxon.nil?
+ def category_filter
+ return nil if @category.nil?
- # Get child taxons at the next depth level
- child_taxons = @taxon.children.order(:lft).select do |child|
- # Only include taxons that have products in the current scope
- @scope.in_taxon(child).exists?
+ # Get child categories at the next depth level
+ child_categories = @category.children.order(:lft).select do |child|
+ # Only include categories that have products in the current scope
+ @scope.in_category(child).exists?
end
- return nil if child_taxons.empty?
+ return nil if child_categories.empty?
{
- id: 'taxons',
- type: 'taxon',
- options: child_taxons.map { |t| taxon_option_data(t) }
+ id: 'categories',
+ type: 'category',
+ options: child_categories.map { |c| category_option_data(c) }
}
end
- def taxon_option_data(taxon)
- count = @scope.in_taxon(taxon).distinct.count
+ def category_option_data(category)
+ count = @scope.in_category(category).distinct.count
{
- id: taxon.prefixed_id,
- name: taxon.name,
- permalink: taxon.permalink,
+ id: category.prefixed_id,
+ name: category.name,
+ permalink: category.permalink,
count: count
}
end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index a8ee41f140..3cad4fd8ff 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -29,9 +29,8 @@ Spree::Core::Engine.add_routes do
get :filters, to: 'products/filters#index'
end
end
- resources :taxonomies, only: [:index, :show]
- resources :taxons, only: [:index, :show], id: /.+/ do
- resources :products, only: [:index], controller: 'taxons/products'
+ resources :categories, only: [:index, :show], id: /.+/ do
+ resources :products, only: [:index], controller: 'categories/products'
end
# Cart
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index f3634227ca..9fb1d873ba 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -115,8 +115,7 @@ module Spree
shipping_method_serializer: 'Spree::Api::V3::ShippingMethodSerializer',
shipping_rate_serializer: 'Spree::Api::V3::ShippingRateSerializer',
stock_location_serializer: 'Spree::Api::V3::StockLocationSerializer',
- taxonomy_serializer: 'Spree::Api::V3::TaxonomySerializer',
- taxon_serializer: 'Spree::Api::V3::TaxonSerializer',
+ category_serializer: 'Spree::Api::V3::CategorySerializer',
order_promotion_serializer: 'Spree::Api::V3::OrderPromotionSerializer',
digital_link_serializer: 'Spree::Api::V3::DigitalLinkSerializer',
gift_card_serializer: 'Spree::Api::V3::GiftCardSerializer',
@@ -153,9 +152,8 @@ module Spree
admin_variant_serializer: 'Spree::Api::V3::Admin::VariantSerializer',
admin_price_serializer: 'Spree::Api::V3::Admin::PriceSerializer',
admin_metafield_serializer: 'Spree::Api::V3::Admin::MetafieldSerializer',
- admin_taxon_serializer: 'Spree::Api::V3::Admin::TaxonSerializer',
+ admin_category_serializer: 'Spree::Api::V3::Admin::CategorySerializer',
admin_line_item_serializer: 'Spree::Api::V3::Admin::LineItemSerializer',
- admin_taxonomy_serializer: 'Spree::Api::V3::Admin::TaxonomySerializer',
admin_option_type_serializer: 'Spree::Api::V3::Admin::OptionTypeSerializer',
admin_option_value_serializer: 'Spree::Api::V3::Admin::OptionValueSerializer',
admin_image_serializer: 'Spree::Api::V3::Admin::ImageSerializer',
diff --git a/spree/api/spec/controllers/spree/api/v3/store/taxons/products_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/categories/products_controller_spec.rb
similarity index 73%
rename from spree/api/spec/controllers/spree/api/v3/store/taxons/products_controller_spec.rb
rename to spree/api/spec/controllers/spree/api/v3/store/categories/products_controller_spec.rb
index 35391a51df..3a8e84d7bf 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/taxons/products_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/categories/products_controller_spec.rb
@@ -1,6 +1,6 @@
require 'spec_helper'
-RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :controller do
+RSpec.describe Spree::Api::V3::Store::Categories::ProductsController, type: :controller do
render_views
include_context 'API v3 Store'
@@ -23,9 +23,9 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
end
describe 'GET #index' do
- context 'finding taxon by permalink' do
- it 'returns active products belonging to the taxon' do
- get :index, params: { taxon_id: taxon.permalink }
+ context 'finding category by permalink' do
+ it 'returns active products belonging to the category' do
+ get :index, params: { category_id: taxon.permalink }
expect(response).to have_http_status(:ok)
expect(json_response['data'].pluck('id')).to include(product_in_taxon.prefixed_id)
@@ -33,17 +33,16 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
expect(json_response['data'].pluck('id')).not_to include(inactive_product_in_taxon.prefixed_id)
end
- it 'returns products from descendant taxons' do
- get :index, params: { taxon_id: taxon.permalink }
+ it 'returns products from descendant categories' do
+ get :index, params: { category_id: taxon.permalink }
expect(response).to have_http_status(:ok)
- # Parent taxon should include products from child taxons
expect(json_response['data'].pluck('id')).to include(product_in_taxon.prefixed_id)
expect(json_response['data'].pluck('id')).to include(product_in_child_taxon.prefixed_id)
end
- it 'returns only products from the specific child taxon when queried directly' do
- get :index, params: { taxon_id: child_taxon.permalink }
+ it 'returns only products from the specific child category when queried directly' do
+ get :index, params: { category_id: child_taxon.permalink }
expect(response).to have_http_status(:ok)
expect(json_response['data'].pluck('id')).to include(product_in_child_taxon.prefixed_id)
@@ -51,9 +50,9 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
end
end
- context 'finding taxon by prefix_id' do
- it 'returns products belonging to the taxon' do
- get :index, params: { taxon_id: taxon.prefixed_id }
+ context 'finding category by prefix_id' do
+ it 'returns products belonging to the category' do
+ get :index, params: { category_id: taxon.prefixed_id }
expect(response).to have_http_status(:ok)
expect(json_response['data'].pluck('id')).to include(product_in_taxon.prefixed_id)
@@ -61,7 +60,7 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
end
it 'returns pagination metadata' do
- get :index, params: { taxon_id: taxon.permalink }
+ get :index, params: { category_id: taxon.permalink }
expect(json_response['meta']).to include('page', 'limit', 'count', 'pages')
end
@@ -69,7 +68,7 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
it 'supports pagination' do
create_list(:product, 3, stores: [store], taxons: [taxon])
- get :index, params: { taxon_id: taxon.permalink, limit: 2, page: 1 }
+ get :index, params: { category_id: taxon.permalink, limit: 2, page: 1 }
expect(json_response['data'].size).to eq(2)
expect(json_response['meta']['page']).to eq(1)
@@ -77,14 +76,14 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
end
context 'error handling' do
- it 'returns not found for non-existent taxon' do
- get :index, params: { taxon_id: 'non-existent' }
+ it 'returns not found for non-existent category' do
+ get :index, params: { category_id: 'non-existent' }
expect(response).to have_http_status(:not_found)
end
- it 'returns not found for taxon from another store' do
- get :index, params: { taxon_id: other_taxon.permalink }
+ it 'returns not found for category from another store' do
+ get :index, params: { category_id: other_taxon.permalink }
expect(response).to have_http_status(:not_found)
end
@@ -94,7 +93,7 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
before { request.headers['X-Spree-Api-Key'] = nil }
it 'returns unauthorized' do
- get :index, params: { taxon_id: taxon.permalink }
+ get :index, params: { category_id: taxon.permalink }
expect(response).to have_http_status(:unauthorized)
end
@@ -115,8 +114,8 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
end
end
- it 'filters products by option value prefixed IDs within taxon' do
- get :index, params: { taxon_id: taxon.permalink, q: { with_option_value_ids: [option_value_red.prefixed_id] } }
+ it 'filters products by option value prefixed IDs within category' do
+ get :index, params: { category_id: taxon.permalink, q: { with_option_value_ids: [option_value_red.prefixed_id] } }
expect(response).to have_http_status(:ok)
ids = json_response['data'].map { |p| p['id'] }
@@ -124,8 +123,8 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
expect(ids).not_to include(product_with_blue.prefixed_id)
end
- it 'filters products by price range within taxon' do
- get :index, params: { taxon_id: taxon.permalink, q: { price_between: [50, 100] } }
+ it 'filters products by price range within category' do
+ get :index, params: { category_id: taxon.permalink, q: { price_between: [50, 100] } }
expect(response).to have_http_status(:ok)
ids = json_response['data'].map { |p| p['id'] }
@@ -133,8 +132,8 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
expect(ids).not_to include(product_with_red.prefixed_id)
end
- it 'filters products by option values and price range combined within taxon' do
- get :index, params: { taxon_id: taxon.permalink, q: { with_option_value_ids: [option_value_red.prefixed_id, option_value_blue.prefixed_id], price_between: [50, 100] } }
+ it 'filters products by option values and price range combined within category' do
+ get :index, params: { category_id: taxon.permalink, q: { with_option_value_ids: [option_value_red.prefixed_id, option_value_blue.prefixed_id], price_between: [50, 100] } }
expect(response).to have_http_status(:ok)
ids = json_response['data'].map { |p| p['id'] }
@@ -157,7 +156,7 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
end
it 'sorts by price low to high' do
- get :index, params: { taxon_id: taxon.permalink, sort: 'price' }
+ get :index, params: { category_id: taxon.permalink, sort: 'price' }
expect(response).to have_http_status(:ok)
prices = json_response['data'].map { |p| p['price']['amount'].to_f }
@@ -165,7 +164,7 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
end
it 'sorts by price high to low' do
- get :index, params: { taxon_id: taxon.permalink, sort: '-price' }
+ get :index, params: { category_id: taxon.permalink, sort: '-price' }
expect(response).to have_http_status(:ok)
prices = json_response['data'].map { |p| p['price']['amount'].to_f }
@@ -173,7 +172,7 @@ RSpec.describe Spree::Api::V3::Store::Taxons::ProductsController, type: :control
end
it 'sorts by name a-z' do
- get :index, params: { taxon_id: taxon.permalink, sort: 'name' }
+ get :index, params: { category_id: taxon.permalink, sort: 'name' }
expect(response).to have_http_status(:ok)
names = json_response['data'].map { |p| p['name'] }
diff --git a/spree/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/categories_controller_spec.rb
similarity index 85%
rename from spree/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb
rename to spree/api/spec/controllers/spree/api/v3/store/categories_controller_spec.rb
index 788b50cd0f..b92acce447 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/categories_controller_spec.rb
@@ -1,6 +1,6 @@
require 'spec_helper'
-RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
+RSpec.describe Spree::Api::V3::Store::CategoriesController, type: :controller do
render_views
include_context 'API v3 Store'
@@ -22,7 +22,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
end
describe 'GET #index' do
- it 'returns taxons for the current store' do
+ it 'returns categories for the current store' do
get :index
expect(response).to have_http_status(:ok)
@@ -36,13 +36,13 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
expect(json_response['meta']).to include('page', 'limit', 'count', 'pages')
end
- it 'returns taxon attributes' do
+ it 'returns category attributes' do
get :index
- taxon_data = json_response['data'].find { |t| t['id'] == taxon.prefixed_id }
- expect(taxon_data).to include('name', 'permalink', 'position', 'depth')
- expect(taxon_data).to include('taxonomy_id', 'parent_id', 'children_count')
- expect(taxon_data).not_to include('lft', 'rgt')
+ category_data = json_response['data'].find { |t| t['id'] == taxon.prefixed_id }
+ expect(category_data).to include('name', 'permalink', 'position', 'depth')
+ expect(category_data).to include('parent_id', 'children_count')
+ expect(category_data).not_to include('lft', 'rgt')
end
context 'with images' do
@@ -51,23 +51,12 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
it 'returns image URLs' do
get :index
- taxon_data = json_response['data'].find { |t| t['id'] == taxon_with_image.prefixed_id }
- expect(taxon_data['image_url']).to be_present
+ category_data = json_response['data'].find { |t| t['id'] == taxon_with_image.prefixed_id }
+ expect(category_data['image_url']).to be_present
end
end
context 'filtering' do
- it 'filters by taxonomy_id' do
- other_taxonomy_in_store = create(:taxonomy, store: store)
- other_taxon = create(:taxon, taxonomy: other_taxonomy_in_store)
-
- get :index, params: { q: { taxonomy_id_eq: taxonomy.id } }
-
- ids = json_response['data'].pluck('id')
- expect(ids).to include(taxon.prefixed_id)
- expect(ids).not_to include(other_taxon.prefixed_id)
- end
-
it 'filters by depth' do
get :index, params: { q: { depth_eq: grandchild_taxon.depth } }
@@ -121,7 +110,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
describe 'GET #show' do
context 'finding by permalink' do
- it 'returns the taxon by permalink' do
+ it 'returns the category by permalink' do
get :show, params: { id: taxon.permalink }
expect(response).to have_http_status(:ok)
@@ -130,7 +119,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
expect(json_response['permalink']).to eq(taxon.permalink)
end
- it 'returns nested taxon by full permalink path' do
+ it 'returns nested category by full permalink path' do
get :show, params: { id: child_taxon.permalink }
expect(response).to have_http_status(:ok)
@@ -140,7 +129,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
end
context 'finding by prefix_id' do
- it 'returns the taxon by prefix_id' do
+ it 'returns the category by prefix_id' do
get :show, params: { id: taxon.prefixed_id }
expect(response).to have_http_status(:ok)
@@ -150,13 +139,13 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
end
end
- it 'returns taxon attributes' do
+ it 'returns category attributes' do
get :show, params: { id: taxon.permalink }
expect(json_response).to include('id', 'name', 'permalink')
end
- it 'includes parent information for child taxon' do
+ it 'includes parent information for child category' do
get :show, params: { id: child_taxon.permalink }
expect(response).to have_http_status(:ok)
@@ -179,7 +168,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
expect(ancestor_ids).to include(taxon.prefixed_id, child_taxon.prefixed_id)
end
- it 'returns empty ancestors for root taxon' do
+ it 'returns empty ancestors for root category' do
root_taxon = taxonomy.root
get :show, params: { id: root_taxon.prefixed_id, expand: 'ancestors' }
@@ -215,7 +204,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
allow(store).to receive(:default_locale).and_return('en')
end
- it 'finds taxon by English permalink with English locale' do
+ it 'finds category by English permalink with English locale' do
request.headers['x-spree-locale'] = 'en'
get :show, params: { id: translated_taxon.permalink }
@@ -224,7 +213,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
expect(json_response['permalink']).to eq(translated_taxon.permalink)
end
- it 'finds taxon by French permalink with French locale' do
+ it 'finds category by French permalink with French locale' do
french_permalink = Mobility.with_locale(:fr) { translated_taxon.permalink }
request.headers['x-spree-locale'] = 'fr'
get :show, params: { id: french_permalink }
@@ -254,13 +243,12 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
create(:taxon, taxonomy: taxonomy, name: 'Electronics')
end
- it 'falls back to default locale when taxon has no translation in requested locale' do
+ it 'falls back to default locale when category has no translation in requested locale' do
request.headers['x-spree-locale'] = 'fr'
get :show, params: { id: english_only_taxon.permalink }
expect(response).to have_http_status(:ok)
expect(json_response['id']).to eq(english_only_taxon.prefixed_id)
- # Name returns English since no French translation exists
expect(json_response['name']).to eq('Electronics')
end
@@ -276,7 +264,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
end
context 'error handling' do
- it 'returns not found for non-existent taxon' do
+ it 'returns not found for non-existent category' do
get :show, params: { id: 'non-existent-permalink' }
expect(response).to have_http_status(:not_found)
@@ -284,7 +272,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
expect(json_response['error']['message']).to be_present
end
- it 'returns not found for taxon from another store' do
+ it 'returns not found for category from another store' do
get :show, params: { id: other_store_taxon.permalink }
expect(response).to have_http_status(:not_found)
@@ -292,7 +280,7 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
end
it 'returns not found for invalid prefix_id' do
- get :show, params: { id: 'txn_invalid123' }
+ get :show, params: { id: 'ctg_invalid123' }
expect(response).to have_http_status(:not_found)
expect(json_response['error']['code']).to eq('record_not_found')
diff --git a/spree/api/spec/controllers/spree/api/v3/store/products/filters_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/products/filters_controller_spec.rb
index bcc737b789..124abc958b 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/products/filters_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/products/filters_controller_spec.rb
@@ -107,27 +107,27 @@ RSpec.describe Spree::Api::V3::Store::Products::FiltersController, type: :contro
expect(json_response['total_count']).to eq(3)
end
- context 'with taxon_id parameter' do
- it 'scopes filters to taxon' do
- get :index, params: { taxon_id: child_taxon1.prefixed_id }
+ context 'with category_id parameter' do
+ it 'scopes filters to category' do
+ get :index, params: { category_id: child_taxon1.prefixed_id }
expect(json_response['total_count']).to eq(2) # Only products in child_taxon1
end
- it 'returns child taxons as filter options' do
- get :index, params: { taxon_id: taxon.prefixed_id }
+ it 'returns child categories as filter options' do
+ get :index, params: { category_id: taxon.prefixed_id }
- taxon_filter = json_response['filters'].find { |f| f['type'] == 'taxon' }
- expect(taxon_filter).to be_present
+ category_filter = json_response['filters'].find { |f| f['type'] == 'category' }
+ expect(category_filter).to be_present
- taxon_options = taxon_filter['options']
- expect(taxon_options.map { |t| t['name'] }).to include('Shirts', 'Pants')
+ category_options = category_filter['options']
+ expect(category_options.map { |t| t['name'] }).to include('Shirts', 'Pants')
end
- it 'returns default_sort from taxon' do
+ it 'returns default_sort from category' do
taxon.update!(sort_order: 'price asc')
- get :index, params: { taxon_id: taxon.prefixed_id }
+ get :index, params: { category_id: taxon.prefixed_id }
expect(json_response['default_sort']).to eq('price')
end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/taxonomies_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/taxonomies_controller_spec.rb
deleted file mode 100644
index 5021c49aec..0000000000
--- a/spree/api/spec/controllers/spree/api/v3/store/taxonomies_controller_spec.rb
+++ /dev/null
@@ -1,97 +0,0 @@
-require 'spec_helper'
-
-RSpec.describe Spree::Api::V3::Store::TaxonomiesController, type: :controller do
- render_views
-
- include_context 'API v3 Store'
-
- let!(:taxonomy) { create(:taxonomy, store: store) }
- let!(:taxonomy2) { create(:taxonomy, store: store) }
- let!(:other_store) { create(:store) }
- let!(:other_store_taxonomy) { create(:taxonomy, store: other_store) }
-
- before do
- request.headers['X-Spree-Api-Key'] = api_key.token
- end
-
- describe 'GET #index' do
- it 'returns taxonomies' do
- get :index
-
- expect(response).to have_http_status(:ok)
- expect(json_response['data'].size).to be >= 2
- end
-
- it 'returns taxonomy attributes' do
- get :index
-
- taxonomy_data = json_response['data'].first
- expect(taxonomy_data).to include('id', 'name')
- end
-
- it 'does not return taxonomies from other stores' do
- get :index
-
- ids = json_response['data'].map { |t| t['id'] }
- expect(ids).not_to include(other_store_taxonomy.prefixed_id)
- end
-
- it 'returns pagination metadata' do
- get :index
-
- expect(json_response['meta']).to include('page', 'count', 'pages')
- end
-
- context 'without API key' do
- before { request.headers['X-Spree-Api-Key'] = nil }
-
- it 'returns unauthorized' do
- get :index
-
- expect(response).to have_http_status(:unauthorized)
- expect(json_response['error']['code']).to eq('invalid_token')
- expect(json_response['error']['message']).to be_present
- end
- end
- end
-
- describe 'GET #show' do
- it 'returns the taxonomy' do
- get :show, params: { id: taxonomy.prefixed_id }
-
- expect(response).to have_http_status(:ok)
- expect(json_response['id']).to eq(taxonomy.prefixed_id)
- expect(json_response['name']).to eq(taxonomy.name)
- end
-
- it 'returns taxonomy with its attributes' do
- get :show, params: { id: taxonomy.prefixed_id }
-
- expect(json_response['id']).to eq(taxonomy.prefixed_id)
- expect(json_response['name']).to be_present
- end
-
- it 'returns root_id for quick access to root taxon' do
- get :show, params: { id: taxonomy.prefixed_id }
-
- expect(json_response['root_id']).to eq(taxonomy.root.prefixed_id)
- end
-
- context 'error handling' do
- it 'returns not found for non-existent taxonomy' do
- get :show, params: { id: 'txnmy_nonexistent' }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('record_not_found')
- expect(json_response['error']['message']).to be_present
- end
-
- it 'returns not found for taxonomy from another store' do
- get :show, params: { id: other_store_taxonomy.prefixed_id }
-
- expect(response).to have_http_status(:not_found)
- expect(json_response['error']['code']).to eq('record_not_found')
- end
- end
- end
-end
diff --git a/spree/api/spec/integration/spree/api/v3/store/taxons_spec.rb b/spree/api/spec/integration/spree/api/v3/store/categories_spec.rb
similarity index 71%
rename from spree/api/spec/integration/spree/api/v3/store/taxons_spec.rb
rename to spree/api/spec/integration/spree/api/v3/store/categories_spec.rb
index e28a66b1b2..330dfd539f 100644
--- a/spree/api/spec/integration/spree/api/v3/store/taxons_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/categories_spec.rb
@@ -2,27 +2,27 @@
require 'swagger_helper'
-RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+RSpec.describe 'Categories API', type: :request, swagger_doc: 'api-reference/store.yaml' do
include_context 'API v3 Store'
let!(:taxonomy) { create(:taxonomy, store: store) }
let!(:root_taxon) { taxonomy.root }
- let!(:taxon) { create(:taxon, taxonomy: taxonomy, parent: root_taxon) }
- let!(:child_taxon) { create(:taxon, taxonomy: taxonomy, parent: taxon) }
- let!(:product) { create(:product, stores: [store], status: 'active', taxons: [taxon]) }
+ let!(:category) { create(:taxon, taxonomy: taxonomy, parent: root_taxon) }
+ let!(:child_category) { create(:taxon, taxonomy: taxonomy, parent: category) }
+ let!(:product) { create(:product, stores: [store], status: 'active', taxons: [category]) }
let!(:other_store) { create(:store) }
let!(:other_taxonomy) { create(:taxonomy, store: other_store) }
- let!(:other_taxon) { create(:taxon, taxonomy: other_taxonomy) }
+ let!(:other_category) { create(:taxon, taxonomy: other_taxonomy) }
- path '/api/v3/store/taxons' do
- get 'List taxons' do
+ path '/api/v3/store/categories' do
+ get 'List categories' do
tags 'Product Catalog'
produces 'application/json'
security [api_key: []]
- description 'Returns a paginated list of taxons (categories) for the current store'
+ description 'Returns a paginated list of categories for the current store'
sdk_example <<~JS
- const taxons = await client.taxons.list({
+ const categories = await client.categories.list({
page: 1,
limit: 25,
})
@@ -36,12 +36,12 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
parameter name: :fields, in: :query, type: :string, required: false,
description: 'Comma-separated list of fields to include (e.g., name,slug,price). id is always included.'
- response '200', 'taxons found' do
+ response '200', 'categories found' do
let(:'x-spree-api-key') { api_key.token }
schema type: :object,
properties: {
- data: { type: :array, items: { '$ref' => '#/components/schemas/Taxon' } },
+ data: { type: :array, items: { '$ref' => '#/components/schemas/Category' } },
meta: { '$ref' => '#/components/schemas/PaginationMeta' }
}
@@ -49,9 +49,9 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
data = JSON.parse(response.body)
expect(data['data']).to be_an(Array)
expect(data['data'].size).to be >= 1
- # Should not include taxons from other stores
+ # Should not include categories from other stores
ids = data['data'].map { |t| t['id'] }
- expect(ids).not_to include(other_taxon.prefixed_id)
+ expect(ids).not_to include(other_category.prefixed_id)
end
end
@@ -65,52 +65,52 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
end
end
- path '/api/v3/store/taxons/{id}' do
- get 'Get a taxon' do
+ path '/api/v3/store/categories/{id}' do
+ get 'Get a category' do
tags 'Product Catalog'
produces 'application/json'
security [api_key: []]
- description 'Returns a single taxon by permalink or prefix ID'
+ description 'Returns a single category by permalink or prefix ID'
sdk_example <<~JS
- const taxon = await client.taxons.get('categories/clothing/shirts', {
- expand: 'children,products',
+ const category = await client.categories.get('categories/clothing/shirts', {
+ expand: 'children',
})
JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: :id, in: :path, type: :string, required: true,
- description: 'Taxon permalink (e.g., categories/clothing/shirts) or prefix ID (e.g., taxon_abc123)'
+ description: 'Category permalink (e.g., clothing/shirts) or prefix ID (e.g., ctg_abc123)'
parameter name: :expand, in: :query, type: :string, required: false,
- description: 'Expand associations (children, products, parent)'
+ description: 'Expand associations (children, parent, ancestors, metafields)'
parameter name: :fields, in: :query, type: :string, required: false,
description: 'Comma-separated list of fields to include (e.g., name,slug,price). id is always included.'
- response '200', 'taxon found by permalink' do
+ response '200', 'category found by permalink' do
let(:'x-spree-api-key') { api_key.token }
- let(:id) { taxon.permalink }
+ let(:id) { category.permalink }
- schema '$ref' => '#/components/schemas/Taxon'
+ schema '$ref' => '#/components/schemas/Category'
run_test! do |response|
data = JSON.parse(response.body)
- expect(data['name']).to eq(taxon.name)
+ expect(data['name']).to eq(category.name)
end
end
- response '200', 'taxon found by prefix ID' do
+ response '200', 'category found by prefix ID' do
let(:'x-spree-api-key') { api_key.token }
- let(:id) { taxon.to_param }
+ let(:id) { category.to_param }
- schema '$ref' => '#/components/schemas/Taxon'
+ schema '$ref' => '#/components/schemas/Category'
run_test! do |response|
data = JSON.parse(response.body)
- expect(data['name']).to eq(taxon.name)
+ expect(data['name']).to eq(category.name)
end
end
- response '404', 'taxon not found' do
+ response '404', 'category not found' do
let(:'x-spree-api-key') { api_key.token }
let(:id) { 'non-existent-permalink' }
@@ -119,9 +119,9 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
run_test!
end
- response '404', 'taxon from other store not accessible' do
+ response '404', 'category from other store not accessible' do
let(:'x-spree-api-key') { api_key.token }
- let(:id) { other_taxon.permalink }
+ let(:id) { other_category.permalink }
schema '$ref' => '#/components/schemas/ErrorResponse'
@@ -130,7 +130,7 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
response '401', 'unauthorized' do
let(:'x-spree-api-key') { 'invalid' }
- let(:id) { taxon.permalink }
+ let(:id) { category.permalink }
schema '$ref' => '#/components/schemas/ErrorResponse'
@@ -139,15 +139,15 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
end
end
- path '/api/v3/store/taxons/{taxon_id}/products' do
- get 'List products in a taxon' do
+ path '/api/v3/store/categories/{category_id}/products' do
+ get 'List products in a category' do
tags 'Product Catalog'
produces 'application/json'
security [api_key: []]
- description 'Returns a paginated list of products belonging to the specified taxon'
+ description 'Returns a paginated list of products belonging to the specified category'
sdk_example <<~JS
- const products = await client.taxons.products.list('categories/clothing', {
+ const products = await client.categories.products.list('categories/clothing', {
page: 1,
limit: 25,
sort: 'price',
@@ -156,8 +156,8 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
- parameter name: :taxon_id, in: :path, type: :string, required: true,
- description: 'Taxon permalink or prefix ID'
+ parameter name: :category_id, in: :path, type: :string, required: true,
+ description: 'Category permalink or prefix ID'
parameter name: :page, in: :query, type: :integer, required: false,
description: 'Page number (default: 1)'
parameter name: :limit, in: :query, type: :integer, required: false,
@@ -177,7 +177,7 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
response '200', 'products found' do
let(:'x-spree-api-key') { api_key.token }
- let(:taxon_id) { taxon.to_param }
+ let(:category_id) { category.to_param }
schema type: :object,
properties: {
@@ -193,9 +193,9 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
end
end
- response '404', 'taxon not found' do
+ response '404', 'category not found' do
let(:'x-spree-api-key') { api_key.token }
- let(:taxon_id) { 'non-existent' }
+ let(:category_id) { 'non-existent' }
schema '$ref' => '#/components/schemas/ErrorResponse'
@@ -204,7 +204,7 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
response '401', 'unauthorized' do
let(:'x-spree-api-key') { 'invalid' }
- let(:taxon_id) { taxon.to_param }
+ let(:category_id) { category.to_param }
schema '$ref' => '#/components/schemas/ErrorResponse'
diff --git a/spree/api/spec/integration/spree/api/v3/store/products_spec.rb b/spree/api/spec/integration/spree/api/v3/store/products_spec.rb
index 102021b318..bad487cb79 100644
--- a/spree/api/spec/integration/spree/api/v3/store/products_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/products_spec.rb
@@ -53,8 +53,8 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
description: 'Sort order. Prefix with - for descending. Values: price, -price, best_selling, name, -name, -available_on, available_on'
parameter name: 'q[name_cont]', in: :query, type: :string, required: false,
description: 'Filter by name containing string'
- parameter name: 'q[taxons_id_eq]', in: :query, type: :string, required: false,
- description: 'Filter by taxon ID'
+ parameter name: 'q[categories_id_eq]', in: :query, type: :string, required: false,
+ description: 'Filter by category ID'
parameter name: 'q[price_gte]', in: :query, type: :number, required: false,
description: 'Filter by minimum price'
parameter name: 'q[price_lte]', in: :query, type: :number, required: false,
@@ -64,7 +64,7 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
parameter name: 'q[in_stock]', in: :query, type: :boolean, required: false,
description: 'Filter to only in-stock products'
parameter name: :expand, in: :query, type: :string, required: false,
- description: 'Comma-separated associations to expand (variants, images, taxons, option_types)'
+ description: 'Comma-separated associations to expand (variants, images, categories, option_types)'
parameter name: :fields, in: :query, type: :string, required: false,
description: 'Comma-separated list of fields to include (e.g., name,slug,price). id is always included.'
@@ -187,20 +187,20 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
Returns available filters for products with their options and counts.
Use this endpoint to build filter UIs for product listing pages.
- The filters are context-aware - when a taxon_id is provided, only filters
- relevant to products in that taxon are returned.
+ The filters are context-aware - when a category_id is provided, only filters
+ relevant to products in that category are returned.
DESC
sdk_example <<~JS
const filters = await client.products.filters({
- taxon_id: 'taxon_abc123',
+ category_id: 'ctg_abc123',
})
JS
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true,
description: 'Publishable API key'
- parameter name: :taxon_id, in: :query, type: :string, required: false,
- description: 'Scope filters to products in this taxon (prefix ID)'
+ parameter name: :category_id, in: :query, type: :string, required: false,
+ description: 'Scope filters to products in this category (prefix ID)'
parameter name: 'q[name_cont]', in: :query, type: :string, required: false,
description: 'Filter by name containing string'
@@ -211,7 +211,7 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
properties: {
filters: {
type: :array,
- description: 'Available filters (price_range, availability, option, taxon)',
+ description: 'Available filters (price_range, availability, option, category)',
items: { type: :object }
},
sort_options: {
@@ -264,9 +264,9 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
end
end
- response '200', 'filters scoped to taxon' do
+ response '200', 'filters scoped to category' do
let(:'x-spree-api-key') { api_key.token }
- let(:taxon_id) { taxon.prefixed_id }
+ let(:category_id) { taxon.prefixed_id }
schema type: :object,
properties: {
@@ -280,10 +280,10 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
run_test! do |response|
data = JSON.parse(response.body)
- # Should include taxon filter with child taxons
- taxon_filter = data['filters'].find { |f| f['type'] == 'taxon' }
- expect(taxon_filter).to be_present
- expect(taxon_filter['options'].map { |t| t['name'] }).to include('Shirts')
+ # Should include category filter with child categories
+ category_filter = data['filters'].find { |f| f['type'] == 'category' }
+ expect(category_filter).to be_present
+ expect(category_filter['options'].map { |t| t['name'] }).to include('Shirts')
end
end
diff --git a/spree/api/spec/integration/spree/api/v3/store/taxonomies_spec.rb b/spree/api/spec/integration/spree/api/v3/store/taxonomies_spec.rb
deleted file mode 100644
index bb1a7302a0..0000000000
--- a/spree/api/spec/integration/spree/api/v3/store/taxonomies_spec.rb
+++ /dev/null
@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-require 'swagger_helper'
-
-RSpec.describe 'Taxonomies API', type: :request, swagger_doc: 'api-reference/store.yaml' do
- include_context 'API v3 Store'
-
- let!(:taxonomy) { create(:taxonomy, store: store) }
- let!(:taxonomy2) { create(:taxonomy, store: store) }
- let!(:other_store) { create(:store) }
- let!(:other_taxonomy) { create(:taxonomy, store: other_store) }
-
- path '/api/v3/store/taxonomies' do
- get 'List taxonomies' do
- tags 'Product Catalog'
- produces 'application/json'
- security [api_key: []]
- description 'Returns a list of taxonomies (category hierarchies) for the current store'
-
- sdk_example <<~JS
- const taxonomies = await client.taxonomies.list({
- page: 1,
- limit: 25,
- })
- JS
-
- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
- parameter name: :page, in: :query, type: :integer, required: false
- parameter name: :limit, in: :query, type: :integer, required: false
- parameter name: :sort, in: :query, type: :string, required: false,
- description: 'Sort order. Prefix with - for descending. Example: name, -name'
- parameter name: :expand, in: :query, type: :string, required: false,
- description: 'Expand root taxon'
- parameter name: :fields, in: :query, type: :string, required: false,
- description: 'Comma-separated list of fields to include (e.g., name,slug,price). id is always included.'
-
- response '200', 'taxonomies found' do
- let(:'x-spree-api-key') { api_key.token }
-
- schema type: :object,
- properties: {
- data: { type: :array, items: { '$ref' => '#/components/schemas/Taxonomy' } },
- meta: { '$ref' => '#/components/schemas/PaginationMeta' }
- }
-
- run_test! do |response|
- data = JSON.parse(response.body)
- expect(data['data'].size).to be >= 2
- end
- end
-
- response '401', 'unauthorized' do
- let(:'x-spree-api-key') { 'invalid' }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
- end
- end
-
- path '/api/v3/store/taxonomies/{id}' do
- get 'Get a taxonomy' do
- tags 'Product Catalog'
- produces 'application/json'
- security [api_key: []]
- description 'Returns a single taxonomy with its taxon tree'
-
- sdk_example <<~JS
- const taxonomy = await client.taxonomies.get('taxonomy_abc123', {
- expand: 'taxons',
- })
- JS
-
- parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
- parameter name: :id, in: :path, type: :string, required: true,
- description: 'Taxonomy ID (prefixed)'
- parameter name: :expand, in: :query, type: :string, required: false,
- description: 'Expand taxons'
- parameter name: :fields, in: :query, type: :string, required: false,
- description: 'Comma-separated list of fields to include (e.g., name,slug,price). id is always included.'
-
- response '200', 'taxonomy found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:id) { taxonomy.to_param }
-
- schema '$ref' => '#/components/schemas/Taxonomy'
-
- run_test! do |response|
- data = JSON.parse(response.body)
- expect(data['name']).to eq(taxonomy.name)
- end
- end
-
- response '404', 'taxonomy not found' do
- let(:'x-spree-api-key') { api_key.token }
- let(:id) { 'tax_nonexistent' }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
-
- response '404', 'taxonomy from other store' do
- let(:'x-spree-api-key') { api_key.token }
- let(:id) { other_taxonomy.to_param }
-
- schema '$ref' => '#/components/schemas/ErrorResponse'
-
- run_test!
- end
- end
- end
-end
diff --git a/spree/api/spec/services/spree/api/v3/filters_aggregator_spec.rb b/spree/api/spec/services/spree/api/v3/filters_aggregator_spec.rb
index 4b8e470387..26d8cd36d0 100644
--- a/spree/api/spec/services/spree/api/v3/filters_aggregator_spec.rb
+++ b/spree/api/spec/services/spree/api/v3/filters_aggregator_spec.rb
@@ -27,7 +27,7 @@ RSpec.describe Spree::Api::V3::FiltersAggregator do
let(:scope) { store.products.available(Time.current, currency) }
- subject { described_class.new(scope: scope, currency: currency, taxon: taxon) }
+ subject { described_class.new(scope: scope, currency: currency, category: taxon) }
describe '#call' do
let(:result) { subject.call }
@@ -58,7 +58,7 @@ RSpec.describe Spree::Api::V3::FiltersAggregator do
end
it 'returns manual as default_sort when no taxon' do
- aggregator = described_class.new(scope: scope, currency: currency, taxon: nil)
+ aggregator = described_class.new(scope: scope, currency: currency, category: nil)
expect(aggregator.call[:default_sort]).to eq('manual')
end
end
@@ -115,24 +115,24 @@ RSpec.describe Spree::Api::V3::FiltersAggregator do
end
end
- describe 'taxon filter' do
- it 'includes child taxons when taxon is provided' do
- taxon_filter = result[:filters].find { |f| f[:type] == 'taxon' }
+ describe 'category filter' do
+ it 'includes child categories when category is provided' do
+ category_filter = result[:filters].find { |f| f[:type] == 'category' }
- expect(taxon_filter).to be_present
- expect(taxon_filter[:options].map { |t| t[:name] }).to include('Child')
+ expect(category_filter).to be_present
+ expect(category_filter[:options].map { |t| t[:name] }).to include('Child')
end
- it 'does not include taxon filter when no taxon provided' do
- aggregator = described_class.new(scope: scope, currency: currency, taxon: nil)
- taxon_filter = aggregator.call[:filters].find { |f| f[:type] == 'taxon' }
+ it 'does not include category filter when no category provided' do
+ aggregator = described_class.new(scope: scope, currency: currency, category: nil)
+ category_filter = aggregator.call[:filters].find { |f| f[:type] == 'category' }
- expect(taxon_filter).to be_nil
+ expect(category_filter).to be_nil
end
- it 'includes product count per taxon' do
- taxon_filter = result[:filters].find { |f| f[:type] == 'taxon' }
- child_option = taxon_filter[:options].find { |t| t[:name] == 'Child' }
+ it 'includes product count per category' do
+ category_filter = result[:filters].find { |f| f[:type] == 'category' }
+ child_option = category_filter[:options].find { |t| t[:name] == 'Child' }
expect(child_option[:count]).to eq(2)
end
diff --git a/spree/core/app/models/concerns/spree/product_scopes.rb b/spree/core/app/models/concerns/spree/product_scopes.rb
index 0bab19aaae..7b92354851 100644
--- a/spree/core/app/models/concerns/spree/product_scopes.rb
+++ b/spree/core/app/models/concerns/spree/product_scopes.rb
@@ -165,6 +165,11 @@ module Spree
where("#{Classification.table_name}.taxon_id" => taxon.cached_self_and_descendants_ids).distinct
end
+ # Alias for in_taxon — public API name
+ add_search_scope :in_category do |category|
+ in_taxon(category)
+ end
+
# This scope selects products in all taxons AND all its descendants
# If you need products only within one taxon use
#
diff --git a/spree/core/app/models/spree/category.rb b/spree/core/app/models/spree/category.rb
new file mode 100644
index 0000000000..b52472101b
--- /dev/null
+++ b/spree/core/app/models/spree/category.rb
@@ -0,0 +1,6 @@
+module Spree
+ # Public API name for Taxon. Will become the base class in 6.0
+ # when spree_taxons table is renamed to spree_categories.
+ class Category < Taxon
+ end
+end
diff --git a/spree/core/app/models/spree/product.rb b/spree/core/app/models/spree/product.rb
index a60b011f91..73c94c32d5 100644
--- a/spree/core/app/models/spree/product.rb
+++ b/spree/core/app/models/spree/product.rb
@@ -40,9 +40,9 @@ module Spree
publishes_lifecycle_events
- MEMOIZED_METHODS = %w[total_on_hand taxonomy_ids taxon_and_ancestors category
+ MEMOIZED_METHODS = %w[total_on_hand taxonomy_ids taxon_and_ancestors
default_variant_id tax_category default_variant variant_for_images
- category_taxon brand_taxon main_taxon
+ brand_taxon main_taxon
purchasable? in_stock? backorderable? digital?]
STATUSES = %w[draft active archived].freeze
@@ -74,6 +74,7 @@ module Spree
has_many :option_types, through: :product_option_types
has_many :classifications, -> { order(created_at: :asc) }, dependent: :delete_all, inverse_of: :product
has_many :taxons, through: :classifications, before_remove: :remove_taxon
+ has_many :categories, through: :classifications, class_name: 'Spree::Category', source: :taxon
has_many :taxonomies, through: :taxons
has_many :product_promotion_rules, class_name: 'Spree::ProductPromotionRule'
@@ -217,7 +218,7 @@ module Spree
alias options product_option_types
self.whitelisted_ransackable_attributes = %w[description name slug discontinue_on status available_on created_at updated_at]
- self.whitelisted_ransackable_associations = %w[taxons stores variants_including_master master variants tags labels
+ self.whitelisted_ransackable_associations = %w[taxons categories stores variants_including_master master variants tags labels
shipping_category classifications option_types]
self.whitelisted_ransackable_scopes = %w[not_discontinued search_by_name in_taxon price_between
price_lte price_gte
@@ -556,40 +557,10 @@ module Spree
brand&.name
end
- # Returns the category for the product
- # If a category association is defined (e.g., belongs_to :category), it will be used
- # Otherwise, falls back to category_taxon for compatibility
- # @return [Spree::Category, Spree::Taxon]
- def category
- if self.class.reflect_on_association(:category)
- super
- else
- Spree::Deprecation.warn('Spree::Product#category is deprecated and will be removed in Spree 5.5. Please use Spree::Product#category_taxon instead.')
- category_taxon
- end
- end
-
- # Returns the category taxon for the product
- # @return [Spree::Taxon]
- def category_taxon
- @category_taxon ||= if classification_count.zero?
- nil
- elsif Spree.use_translations?
- taxons.joins(:taxonomy).
- join_translation_table(Taxonomy).
- order(depth: :desc).
- find_by(Taxonomy.translation_table_alias => { name: Spree.t(:taxonomy_categories_name) })
- elsif taxons.loaded?
- taxons.find { |taxon| taxon.taxonomy.name == Spree.t(:taxonomy_categories_name) }
- else
- taxons.joins(:taxonomy).order(depth: :desc).find_by(Taxonomy.table_name => { name: Spree.t(:taxonomy_categories_name) })
- end
- end
-
def main_taxon
return if classification_count.zero?
- @main_taxon ||= category_taxon || taxons.first
+ @main_taxon ||= taxons.first
end
def taxons_for_store(store)
diff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rb
index 0f384a2cad..72842a611f 100644
--- a/spree/core/app/models/spree/store.rb
+++ b/spree/core/app/models/spree/store.rb
@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
require 'uri'
module Spree
class Store < Spree.base_class
- has_prefix_id :store # Spree-specific: store
+ has_prefix_id :store # Spree-specific: store
include FriendlyId
include Spree::TranslatableResource
@@ -81,6 +83,7 @@ module Spree
has_many :taxonomies, class_name: 'Spree::Taxonomy'
has_many :taxons, through: :taxonomies, class_name: 'Spree::Taxon'
+ has_many :categories, through: :taxonomies, class_name: 'Spree::Category', source: :taxons
has_many :store_promotions, class_name: 'Spree::StorePromotion'
has_many :promotions, through: :store_promotions, class_name: 'Spree::Promotion'
@@ -106,8 +109,6 @@ module Spree
has_many :api_keys, class_name: 'Spree::ApiKey', dependent: :destroy
-
-
#
# Validations
#
@@ -119,9 +120,9 @@ module Spree
validates :mail_from_address, email: { allow_blank: false }
# FIXME: we should remove this condition in v5
if !ENV['SPREE_DISABLE_DB_CONNECTION'] &&
- connected? &&
- table_exists? &&
- connection.column_exists?(:spree_stores, :new_order_notifications_email)
+ connected? &&
+ table_exists? &&
+ connection.column_exists?(:spree_stores, :new_order_notifications_email)
validates :new_order_notifications_email, email: { allow_blank: true }
end
validates :mailer_logo, content_type: Rails.application.config.active_storage.web_image_content_types
@@ -137,8 +138,6 @@ module Spree
before_validation :set_default_code, on: :create
before_save :ensure_default_exists_and_is_unique
after_create :ensure_default_market
- after_create :ensure_default_taxonomies_are_created
- after_create :ensure_default_automatic_taxons
after_create :create_default_policies
#
@@ -282,18 +281,18 @@ module Spree
# @return [ActiveRecord::Relation<Spree::Country>]
def countries_with_shipping_coverage
zone_ids = Spree::Zone
- .joins(:shipping_methods)
- .select(:id)
+ .joins(:shipping_methods)
+ .select(:id)
country_zone_country_ids = Spree::ZoneMember
- .where(zone_id: zone_ids, zoneable_type: 'Spree::Country')
- .select(:zoneable_id)
+ .where(zone_id: zone_ids, zoneable_type: 'Spree::Country')
+ .select(:zoneable_id)
state_zone_country_ids = Spree::State
- .where(id: Spree::ZoneMember
- .where(zone_id: zone_ids, zoneable_type: 'Spree::State')
- .select(:zoneable_id))
- .select(:country_id)
+ .where(id: Spree::ZoneMember
+ .where(zone_id: zone_ids, zoneable_type: 'Spree::State')
+ .select(:zoneable_id))
+ .select(:country_id)
Spree::Country
.where(id: country_zone_country_ids)
@@ -307,7 +306,8 @@ module Spree
@default_stock_location ||= begin
stock_location_scope = Spree::StockLocation.where(default: true)
stock_location_scope.first || ActiveRecord::Base.connected_to(role: :writing) do
- stock_location_scope.create(default: true, name: Spree.t(:default_stock_location_name), country: default_country)
+ stock_location_scope.create(default: true, name: Spree.t(:default_stock_location_name),
+ country: default_country)
end
end
end
@@ -351,7 +351,25 @@ module Spree
end
end
+ def create_default_policies
+ Spree::Events.disable do
+ [
+ translate_with_store_locale_fallback('spree.terms_of_service'),
+ translate_with_store_locale_fallback('spree.privacy_policy'),
+ translate_with_store_locale_fallback('spree.returns_policy'),
+ translate_with_store_locale_fallback('spree.shipping_policy')
+ ].each do |policy_name|
+ # Manual exists?/create to work around Mobility bug with find_or_create_by
+ next if policies.with_matching_name(policy_name).exists?
+
+ policies.create(name: policy_name)
+ end
+ end
+ end
+
def ensure_default_taxonomies_are_created
+ Spree::Deprecation.warn('Store#ensure_default_taxonomies_are_created is deprecated and will be removed in Spree 5.5. Please remove it from your codebase')
+
Spree::Events.disable do
[
translate_with_store_locale_fallback('spree.taxonomy_categories_name'),
@@ -367,13 +385,16 @@ module Spree
end
def ensure_default_automatic_taxons
+ Spree::Deprecation.warn('Store#ensure_default_automatic_taxons is deprecated and will be removed in Spree 5.5. Please remove it from your codebase')
+
Spree::Events.disable do
# Use Mobility-safe lookup for taxonomy
collections_taxonomy = taxonomies.with_matching_name(translate_with_store_locale_fallback('spree.taxonomy_collections_name')).first
return unless collections_taxonomy.present?
automatic_taxons_config = [
- { name: translate_with_store_locale_fallback('spree.automatic_taxon_names.on_sale'), rule_type: 'Spree::TaxonRules::Sale', rule_value: 'true' },
+ { name: translate_with_store_locale_fallback('spree.automatic_taxon_names.on_sale'),
+ rule_type: 'Spree::TaxonRules::Sale', rule_value: 'true' },
{ name: translate_with_store_locale_fallback('spree.automatic_taxon_names.new_arrivals'), rule_type: 'Spree::TaxonRules::AvailableOn', rule_value: 30 }
]
@@ -395,22 +416,6 @@ module Spree
end
end
- def create_default_policies
- Spree::Events.disable do
- [
- translate_with_store_locale_fallback('spree.terms_of_service'),
- translate_with_store_locale_fallback('spree.privacy_policy'),
- translate_with_store_locale_fallback('spree.returns_policy'),
- translate_with_store_locale_fallback('spree.shipping_policy')
- ].each do |policy_name|
- # Manual exists?/create to work around Mobility bug with find_or_create_by
- next if policies.with_matching_name(policy_name).exists?
-
- policies.create(name: policy_name)
- end
- end
- end
-
# Translates a key using the store's default locale with fallback to :en
def translate_with_store_locale_fallback(key)
locale = default_locale.presence&.to_sym || :en
diff --git a/spree/core/app/models/spree/taxon.rb b/spree/core/app/models/spree/taxon.rb
index 613956894f..757ab5e5d2 100644
--- a/spree/core/app/models/spree/taxon.rb
+++ b/spree/core/app/models/spree/taxon.rb
@@ -2,7 +2,7 @@ require 'stringex'
module Spree
class Taxon < Spree.base_class
- has_prefix_id :txn # Spree-specific: taxon
+ has_prefix_id :ctg
RULES_MATCH_POLICIES = %w[all any].freeze
SORT_ORDERS = [
diff --git a/spree/core/spec/models/spree/product_spec.rb b/spree/core/spec/models/spree/product_spec.rb
index dd457f8a6a..5b234a1e79 100644
--- a/spree/core/spec/models/spree/product_spec.rb
+++ b/spree/core/spec/models/spree/product_spec.rb
@@ -636,7 +636,7 @@ describe Spree::Product, type: :model do
end
describe '#brand_taxon' do
- let(:taxonomy) { store.taxonomies.find_by(name: Spree.t(:taxonomy_brands_name)) }
+ let(:taxonomy) { store.taxonomies.find_by(name: Spree.t(:taxonomy_brands_name)) || create(:taxonomy, name: Spree.t(:taxonomy_brands_name), store: store) }
let(:product) { create(:product, taxons: [taxonomy.taxons.first], stores: [store]) }
it 'fetches Brand Taxon' do
@@ -645,7 +645,7 @@ describe Spree::Product, type: :model do
end
describe '#brand' do
- let(:taxonomy) { store.taxonomies.find_by(name: Spree.t(:taxonomy_brands_name)) }
+ let(:taxonomy) { store.taxonomies.find_by(name: Spree.t(:taxonomy_brands_name)) || create(:taxonomy, name: Spree.t(:taxonomy_brands_name), store: store) }
let(:product) { create(:product, taxons: [taxonomy.taxons.first], stores: [store]) }
context 'when brand association is not defined' do
@@ -683,40 +683,6 @@ describe Spree::Product, type: :model do
end
end
- describe '#category_taxon' do
- let(:taxonomy) { store.taxonomies.find_by(name: Spree.t(:taxonomy_categories_name)) }
- let(:product) { create(:product, taxons: [taxonomy.taxons.first], stores: [store]) }
-
- it 'fetches Category Taxon' do
- expect(product.category_taxon).to eql(taxonomy.taxons.first)
- end
- end
-
- describe '#category' do
- let(:taxonomy) { store.taxonomies.find_by(name: Spree.t(:taxonomy_categories_name)) }
- let(:product) { create(:product, taxons: [taxonomy.taxons.first], stores: [store]) }
-
- context 'when category association is not defined' do
- it 'falls back to category_taxon' do
- expect(product.category).to eql(taxonomy.taxons.first)
- end
- end
-
- context 'when category association is defined' do
- let(:category_class) { Class.new(Spree::Base) { self.table_name = 'spree_taxons' } }
- let(:category) { category_class.first }
-
- before do
- stub_const('Spree::Category', category_class)
- allow(Spree::Product).to receive(:reflect_on_association).with(:category).and_return(double(name: :category))
- end
-
- it 'checks for the category association' do
- expect(Spree::Product.reflect_on_association(:category)).to be_truthy
- end
- end
- end
-
describe '#backordered?' do
let!(:product) { create(:product, stores: [store]) }
diff --git a/spree/core/spec/models/spree/report_line_items/products_performance_spec.rb b/spree/core/spec/models/spree/report_line_items/products_performance_spec.rb
index c3a53fa08e..16add1ad44 100644
--- a/spree/core/spec/models/spree/report_line_items/products_performance_spec.rb
+++ b/spree/core/spec/models/spree/report_line_items/products_performance_spec.rb
@@ -25,7 +25,7 @@ RSpec.describe Spree::ReportLineItems::ProductsPerformance do
end
describe '#category_levels' do
- let(:taxonomy) { store.taxonomies.first }
+ let(:taxonomy) { store.taxonomies.first || create(:taxonomy, name: 'Categories', store: store) }
let(:taxon) { create(:taxon, name: 'Shoes', taxonomy: taxonomy) }
context 'when product has taxons' do
diff --git a/spree/core/spec/models/spree/store_spec.rb b/spree/core/spec/models/spree/store_spec.rb
index 4305408837..d7f7012f16 100644
--- a/spree/core/spec/models/spree/store_spec.rb
+++ b/spree/core/spec/models/spree/store_spec.rb
@@ -211,82 +211,6 @@ describe Spree::Store, type: :model, without_global_store: true do
end
end
- describe '#ensure_default_taxonomies_are_created' do
- let(:store) { build(:store) }
-
- it 'creates default taxonomies' do
- expect { store.save! }.to change(Spree::Taxonomy, :count).by(3)
-
- expect(store.taxonomies.count).to eq(3)
- expect(store.taxonomies.pluck(:name)).to contain_exactly(
- Spree.t(:taxonomy_categories_name),
- Spree.t(:taxonomy_brands_name),
- Spree.t(:taxonomy_collections_name)
- )
- end
-
- it 'is idempotent - does not create duplicates when called multiple times' do
- store.save!
-
- expect { store.send(:ensure_default_taxonomies_are_created) }.not_to change(Spree::Taxonomy, :count)
- expect(store.taxonomies.count).to eq(3)
- end
-
- context 'with non-English store locale' do
- let(:store) { build(:store, default_locale: 'de') }
-
- before do
- # Add German translations for taxonomy names
- I18n.backend.store_translations(:de, {
- spree: {
- taxonomy_categories_name: 'Kategorien',
- taxonomy_brands_name: 'Marken',
- taxonomy_collections_name: 'Kollektionen'
- }
- })
- end
-
- it 'creates taxonomies with translated names in store locale' do
- store.save!
-
- # Taxonomies are created with the translated name in the base column
- expect(store.taxonomies.pluck(:name)).to contain_exactly('Kategorien', 'Marken', 'Kollektionen')
- end
-
- it 'falls back to English when translation is missing' do
- # Remove the German translation for categories
- I18n.backend.store_translations(:de, { spree: { taxonomy_categories_name: nil } })
-
- store.save!
-
- # Categories falls back to English, others use German
- expect(store.taxonomies.pluck(:name)).to include('Categories') # fallback to English
- expect(store.taxonomies.pluck(:name)).to include('Marken')
- expect(store.taxonomies.pluck(:name)).to include('Kollektionen')
- end
- end
- end
-
- describe '#ensure_default_automatic_taxons' do
- let(:store) { build(:store) }
- let(:collections_taxonomy) { store.taxonomies.with_matching_name(Spree.t(:taxonomy_collections_name)).first }
-
- it 'creates automatic taxons on the collections taxonomy' do
- expect { store.save! }.to change(Spree::Taxon.automatic, :count).by(2)
-
- expect(store.reload.taxons.automatic.count).to eq(2)
- expect(store.taxons.automatic.pluck(:name)).to contain_exactly('New arrivals', 'On sale')
- expect(store.taxons.automatic.pluck(:taxonomy_id).uniq).to contain_exactly(collections_taxonomy.id)
- end
-
- it 'is idempotent - does not create duplicates when called multiple times' do
- store.save!
-
- expect { store.send(:ensure_default_automatic_taxons) }.not_to change(Spree::Taxon.automatic, :count)
- expect(store.taxons.automatic.count).to eq(2)
- end
- end
-
end
context 'Validations' do
diff --git a/spree/core/spec/models/spree/taxon_spec.rb b/spree/core/spec/models/spree/taxon_spec.rb
index 30e96c7814..fb1f6d5bbb 100644
--- a/spree/core/spec/models/spree/taxon_spec.rb
+++ b/spree/core/spec/models/spree/taxon_spec.rb
@@ -2,7 +2,7 @@ require 'spec_helper'
describe Spree::Taxon, type: :model do
let(:store) { @default_store }
- let(:taxonomy) { store.taxonomies.first }
+ let(:taxonomy) { store.taxonomies.first || create(:taxonomy, store: store) }
let(:taxon) { build(:taxon, name: 'Ruby on Rails', parent: nil) }
it_behaves_like 'metadata'
@@ -332,7 +332,7 @@ describe Spree::Taxon, type: :model do
describe '#localized_slugs_for_store' do
let(:store) { create(:store, default_locale: 'fr', supported_locales: 'en,pl,fr') }
- let(:taxonomy) { store.taxonomies.find_by(name: Spree.t(:taxonomy_categories_name)) }
+ let(:taxonomy) { store.taxonomies.find_by(name: Spree.t(:taxonomy_categories_name)) || create(:taxonomy, name: Spree.t(:taxonomy_categories_name), store: store) }
let(:taxon) { create(:taxon, taxonomy: taxonomy, permalink: 'test_slug_en') }
let!(:taxon_translation_fr) { taxon.translations.create(slug: 'test_slug_fr', locale: 'fr') }
let!(:root_taxon) { taxonomy.taxons.find_by(parent_id: nil) }
diff --git a/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rb b/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rb
index 03898cc0cd..9353dc2c9e 100644
--- a/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rb
+++ b/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rb
@@ -223,7 +223,7 @@ RSpec.describe Spree::Imports::RowProcessors::ProductVariant, type: :service do
end
it 'assigns taxons to the product' do
- expect { subject.process! }.to change { Spree::Taxon.count }.by(6)
+ expect { subject.process! }.to change { Spree::Taxon.count }.by(9) # 3 root taxons (from 3 taxonomies) + 6 leaf taxons
expect(product.reload.taxons.map(&:pretty_name)).to contain_exactly(
'Categories -> Men -> Clothing -> Shirts',
@@ -233,15 +233,15 @@ RSpec.describe Spree::Imports::RowProcessors::ProductVariant, type: :service do
end
context 'when the taxons already exist' do
- let(:categories_taxonomy) { store.taxonomies.find_by(name: 'Categories') }
+ let(:categories_taxonomy) { store.taxonomies.find_by(name: 'Categories') || create(:taxonomy, name: 'Categories', store: store) }
let!(:men_taxon) { create(:taxon, name: 'Men', taxonomy: categories_taxonomy, parent: categories_taxonomy.root) }
let!(:clothing_taxon) { create(:taxon, name: 'clothing', taxonomy: categories_taxonomy, parent: men_taxon) }
let!(:shirts_category_taxon) { create(:taxon, name: 'Shirts', taxonomy: categories_taxonomy, parent: clothing_taxon) }
- let(:brands_taxonomy) { store.taxonomies.find_by(name: 'Brands') }
+ let(:brands_taxonomy) { store.taxonomies.find_by(name: 'Brands') || create(:taxonomy, name: 'Brands', store: store) }
let!(:awesome_brand_taxon) { create(:taxon, name: 'Awesome brand', taxonomy: brands_taxonomy, parent: brands_taxonomy.root) }
- let(:collections_taxonomy) { store.taxonomies.find_by(name: 'Collections') }
+ let(:collections_taxonomy) { store.taxonomies.find_by(name: 'Collections') || create(:taxonomy, name: 'Collections', store: store) }
let!(:summer_taxon) { create(:taxon, name: 'Summer', taxonomy: collections_taxonomy, parent: collections_taxonomy.root) }
let!(:shirts_collection_taxon) { create(:taxon, name: 'Shirts', taxonomy: collections_taxonomy, parent: summer_taxon) }
@@ -266,7 +266,7 @@ RSpec.describe Spree::Imports::RowProcessors::ProductVariant, type: :service do
end
context 'when taxons are not provided' do
- let(:categories_taxonomy) { store.taxonomies.find_by(name: 'Categories') }
+ let(:categories_taxonomy) { store.taxonomies.find_by(name: 'Categories') || create(:taxonomy, name: 'Categories', store: store) }
let!(:men_taxon) { create(:taxon, name: 'Men', taxonomy: categories_taxonomy, parent: categories_taxonomy.root) }
let!(:clothing_taxon) { create(:taxon, name: 'Clothing', taxonomy: categories_taxonomy, parent: men_taxon) }
@@ -297,7 +297,7 @@ RSpec.describe Spree::Imports::RowProcessors::ProductVariant, type: :service do
end
it 'skips invalid taxons' do
- expect { subject.process! }.to change { Spree::Taxon.count }.by(2)
+ expect { subject.process! }.to change { Spree::Taxon.count }.by(3) # 1 root taxon (from 1 taxonomy) + 2 leaf taxons
expect(product.reload.taxons.map(&:pretty_name)).to contain_exactly(
'Categories -> Men -> Shirts'
@@ -306,7 +306,7 @@ RSpec.describe Spree::Imports::RowProcessors::ProductVariant, type: :service do
end
context 'when importing a variant row with no taxons' do
- let(:categories_taxonomy) { store.taxonomies.find_by(name: 'Categories') }
+ let(:categories_taxonomy) { store.taxonomies.find_by(name: 'Categories') || create(:taxonomy, name: 'Categories', store: store) }
let!(:men_taxon) { create(:taxon, name: 'Men', taxonomy: categories_taxonomy, parent: categories_taxonomy.root) }
let!(:clothing_taxon) { create(:taxon, name: 'Clothing', taxonomy: categories_taxonomy, parent: men_taxon) }
diff --git a/spree/core/spec/services/spree/products/auto_match_taxons_spec.rb b/spree/core/spec/services/spree/products/auto_match_taxons_spec.rb
index ed035ab309..90cf39f465 100644
--- a/spree/core/spec/services/spree/products/auto_match_taxons_spec.rb
+++ b/spree/core/spec/services/spree/products/auto_match_taxons_spec.rb
@@ -7,7 +7,7 @@ RSpec.describe Spree::Products::AutoMatchTaxons do
let(:product) { create(:product, stores: [store]) }
context 'when product matches new taxon' do
- let!(:taxon) { create(:automatic_taxon, taxonomy: store.taxonomies.first) }
+ let!(:taxon) { create(:automatic_taxon, taxonomy: store.taxonomies.first || create(:taxonomy, store: store)) }
before do
create(:tag_taxon_rule, taxon: taxon, value: 'cruelty-free')
@@ -32,7 +32,7 @@ RSpec.describe Spree::Products::AutoMatchTaxons do
end
context 'when product no longer matches taxon' do
- let(:taxon) { create(:automatic_taxon, taxonomy: store.taxonomies.first) }
+ let(:taxon) { create(:automatic_taxon, taxonomy: store.taxonomies.first || create(:taxonomy, store: store)) }
before do
create(:tag_taxon_rule, taxon: taxon, value: 'cruelty-free')