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.

Rename `per_page` to `limit`, and `includes` to `expand` in API v3 (#13717)

Damian Legawiecb31b3edcb1e6
diff --git a/packages/next/CHANGELOG.md b/packages/next/CHANGELOG.md
index bb05d4c3d6..2c6c13b30b 100644
--- a/packages/next/CHANGELOG.md
+++ b/packages/next/CHANGELOG.md
@@ -1,5 +1,12 @@
# @spree/next
+## 0.6.5
+
+### Patch Changes
+
+- Rename `per_page` pagination parameter to `limit`
+- Rename `includes` query parameter to `expand`
+
## 0.6.4
### Patch Changes
diff --git a/packages/next/README.md b/packages/next/README.md
index dd2c9c4894..00976d9b5f 100644
--- a/packages/next/README.md
+++ b/packages/next/README.md
@@ -39,7 +39,7 @@ initSpreeNext({
import { listProducts, getProduct, listTaxons } from '@spree/next';
export default async function ProductsPage() {
- const products = await listProducts({ per_page: 12 });
+ const products = await listProducts({ limit: 12 });
const categories = await listTaxons({ depth_eq: 1 });
return (
@@ -93,7 +93,7 @@ Plain async functions for reading data in Server Components. Wrap with `"use cac
```typescript
import { listProducts, getProduct, getProductFilters } from '@spree/next';
-const products = await listProducts({ per_page: 25, includes: 'variants,images' });
+const products = await listProducts({ limit: 25, expand: 'variants,images' });
const product = await getProduct('spree-tote');
const filters = await getProductFilters({ taxon_id: 'txn_123' });
```
@@ -106,9 +106,9 @@ import { listTaxonomies, getTaxonomy } from '@spree/next';
const taxons = await listTaxons({ depth_eq: 1 });
const taxon = await getTaxon('categories/clothing');
-const products = await listTaxonProducts('categories/clothing', { per_page: 12 });
+const products = await listTaxonProducts('categories/clothing', { limit: 12 });
-const taxonomies = await listTaxonomies({ includes: 'taxons' });
+const taxonomies = await listTaxonomies({ expand: 'taxons' });
const taxonomy = await getTaxonomy('tax_123');
```
@@ -261,7 +261,7 @@ export const config = {
Data functions work without any locale arguments:
```typescript
-const products = await listProducts({ per_page: 10 });
+const products = await listProducts({ limit: 10 });
const taxon = await getTaxon('categories/clothing');
```
@@ -278,7 +278,7 @@ await setLocale({ country: 'de', locale: 'de' });
You can still pass locale options explicitly — they override auto-detected values:
```typescript
-const products = await listProducts({ per_page: 10 }, { locale: 'fr', country: 'FR' });
+const products = await listProducts({ limit: 10 }, { locale: 'fr', country: 'FR' });
```
## TypeScript
diff --git a/packages/next/package.json b/packages/next/package.json
index 7c7dbdd6fc..bd4eba5426 100644
--- a/packages/next/package.json
+++ b/packages/next/package.json
@@ -1,6 +1,6 @@
{
"name": "@spree/next",
- "version": "0.6.4",
+ "version": "0.6.5",
"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.6.3",
+ "@spree/sdk": ">=0.6.6",
"next": ">=15.0.0",
"react": ">=19.0.0"
},
diff --git a/packages/next/src/actions/checkout.ts b/packages/next/src/actions/checkout.ts
index 5457471248..9e33171fd0 100644
--- a/packages/next/src/actions/checkout.ts
+++ b/packages/next/src/actions/checkout.ts
@@ -21,7 +21,7 @@ export async function getCheckout(
const options = await getCheckoutOptions();
return getClient().store.orders.get(
orderId,
- { includes: 'line_items,shipments,ship_address,bill_address' },
+ { expand: 'line_items,shipments,ship_address,bill_address' },
options
);
}
diff --git a/packages/next/src/data/countries.ts b/packages/next/src/data/countries.ts
index 15d2926b61..0fb2a34479 100644
--- a/packages/next/src/data/countries.ts
+++ b/packages/next/src/data/countries.ts
@@ -5,7 +5,7 @@ import type { SpreeNextOptions } from '../types';
/**
* List countries available in the store.
- * Use ?include=market to include market details (currency, locale, tax_inclusive).
+ * Use ?expand=market to expand market details (currency, locale, tax_inclusive).
*/
export async function listCountries(
options?: SpreeNextOptions
@@ -17,11 +17,11 @@ export async function listCountries(
/**
* Get a country by ISO code.
* @param iso - ISO 3166-1 alpha-2 code (e.g., "US", "DE")
- * @param params - Optional params (e.g., { include: 'states' } or { include: 'market' })
+ * @param params - Optional params (e.g., { expand: 'states' } or { expand: 'market' })
*/
export async function getCountry(
iso: string,
- params?: { include?: string },
+ params?: { expand?: string },
options?: SpreeNextOptions
): Promise<StoreCountry> {
const resolved = options ?? await getLocaleOptions();
diff --git a/packages/next/src/data/markets.ts b/packages/next/src/data/markets.ts
index e55c091736..db617ad553 100644
--- a/packages/next/src/data/markets.ts
+++ b/packages/next/src/data/markets.ts
@@ -5,7 +5,7 @@ import type { SpreeNextOptions } from '../types';
/**
* List all markets for the current store.
- * Each market includes currency, locales, tax_inclusive flag, and countries.
+ * Each market contains currency, locales, tax_inclusive flag, and countries.
*/
export async function listMarkets(
options?: SpreeNextOptions
@@ -58,7 +58,7 @@ export async function listMarketCountries(
export async function getMarketCountry(
marketId: string,
iso: string,
- params?: { include?: string },
+ params?: { expand?: string },
options?: SpreeNextOptions
): Promise<StoreCountry> {
const resolved = options ?? await getLocaleOptions();
diff --git a/packages/next/src/data/products.ts b/packages/next/src/data/products.ts
index 3865a0d7fa..fc78da72c5 100644
--- a/packages/next/src/data/products.ts
+++ b/packages/next/src/data/products.ts
@@ -21,7 +21,7 @@ export async function listProducts(
*/
export async function getProduct(
slugOrId: string,
- params?: { includes?: string },
+ params?: { expand?: string },
options?: SpreeNextOptions
): Promise<StoreProduct> {
const resolved = options ?? await getLocaleOptions();
diff --git a/packages/next/tests/actions/checkout.test.ts b/packages/next/tests/actions/checkout.test.ts
index 8dab2542e3..10cc3f04d7 100644
--- a/packages/next/tests/actions/checkout.test.ts
+++ b/packages/next/tests/actions/checkout.test.ts
@@ -51,7 +51,7 @@ describe('checkout actions', () => {
});
describe('getCheckout', () => {
- it('fetches order with includes and auth options', async () => {
+ it('fetches order with expand and auth options', async () => {
const mockOrder = { id: '1', number: 'R123', line_items: [{ id: 'li1' }] };
mockClient.store.orders.get.mockResolvedValue(mockOrder);
@@ -59,7 +59,7 @@ describe('checkout actions', () => {
expect(result).toEqual(mockOrder);
expect(mockClient.store.orders.get).toHaveBeenCalledWith(
'1',
- { includes: 'line_items,shipments,ship_address,bill_address' },
+ { expand: 'line_items,shipments,ship_address,bill_address' },
{ orderToken: 'order_token_123', token: 'jwt_token_abc' }
);
});
diff --git a/packages/next/tests/actions/orders.test.ts b/packages/next/tests/actions/orders.test.ts
index 210b8f1967..9ebb6d5277 100644
--- a/packages/next/tests/actions/orders.test.ts
+++ b/packages/next/tests/actions/orders.test.ts
@@ -92,11 +92,11 @@ describe('order actions', () => {
const mockOrder = { id: '1', number: 'R001' };
mockClient.store.orders.get.mockResolvedValue(mockOrder);
- const result = await getOrder('R001', { includes: 'line_items' });
+ const result = await getOrder('R001', { expand: 'line_items' });
expect(result).toEqual(mockOrder);
expect(mockClient.store.orders.get).toHaveBeenCalledWith(
'R001',
- { includes: 'line_items' },
+ { expand: 'line_items' },
expect.objectContaining({ token: expect.any(String) })
);
});
diff --git a/packages/sdk/CHANGELOG.md b/packages/sdk/CHANGELOG.md
index d775efea77..22d189125b 100644
--- a/packages/sdk/CHANGELOG.md
+++ b/packages/sdk/CHANGELOG.md
@@ -1,5 +1,12 @@
# @spree/sdk
+## 0.6.4
+
+### Patch Changes
+
+- Rename `per_page` pagination parameter to `limit`
+- Rename `includes` query parameter to `expand`
+
## 0.6.3
### Patch Changes
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index 75e624130b..d1ead41782 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -26,8 +26,8 @@ const client = createSpreeClient({
// Browse products (Store API)
const products = await client.store.products.list({
- per_page: 10,
- includes: 'variants,images',
+ limit: 10,
+ expand: 'variants,images',
});
// Get a single product
@@ -147,15 +147,15 @@ const store = await client.store.store.get();
// List products with filtering
const products = await client.store.products.list({
page: 1,
- per_page: 25,
+ limit: 25,
name_cont: 'shirt',
sort: 'price asc',
- includes: 'variants,images,taxons',
+ expand: 'variants,images,taxons',
});
// Get single product by ID or slug
const product = await client.store.products.get('spree-tote', {
- includes: 'variants,images',
+ expand: 'variants,images',
});
// Get available filters (price range, availability, options, taxons)
@@ -169,12 +169,12 @@ const filters = await client.store.products.filters({
```typescript
// List taxonomies
const taxonomies = await client.store.taxonomies.list({
- includes: 'taxons',
+ expand: 'taxons',
});
// Get taxonomy with taxons
const categories = await client.store.taxonomies.get('tax_123', {
- includes: 'root,taxons',
+ expand: 'root,taxons',
});
// List taxons with filtering
@@ -185,14 +185,14 @@ const taxons = await client.store.taxons.list({
// Get single taxon by ID or permalink
const taxon = await client.store.taxons.get('categories/clothing', {
- includes: 'ancestors,children', // For breadcrumbs and subcategories
+ expand: 'ancestors,children', // For breadcrumbs and subcategories
});
// List products in a category
const categoryProducts = await client.store.taxons.products.list('categories/clothing', {
page: 1,
- per_page: 12,
- includes: 'images,default_variant',
+ limit: 12,
+ expand: 'images,default_variant',
});
```
@@ -225,7 +225,7 @@ const options = { orderToken: cart.order_token };
// Get order by ID or number
const order = await client.store.orders.get('R123456789', {
- includes: 'line_items,shipments',
+ expand: 'line_items,shipments',
}, options);
// Update order (email, addresses)
@@ -448,7 +448,7 @@ const { data: wishlists } = await client.store.wishlists.list({}, options);
// Get wishlist by ID
const wishlist = await client.store.wishlists.get('wl_xxx', {
- includes: 'wished_items',
+ expand: 'wished_items',
}, options);
// Create wishlist
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 2ca27110c9..ee4ee07c79 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -1,6 +1,6 @@
{
"name": "@spree/sdk",
- "version": "0.6.3",
+ "version": "0.6.4",
"description": "Official TypeScript SDK for Spree Commerce API",
"type": "module",
"main": "./dist/index.cjs",
diff --git a/packages/sdk/src/params.ts b/packages/sdk/src/params.ts
index ef28b92b73..d9cf0d2ada 100644
--- a/packages/sdk/src/params.ts
+++ b/packages/sdk/src/params.ts
@@ -1,14 +1,14 @@
/**
* Keys that are passed through to the API without wrapping in q[...].
*/
-const PASSTHROUGH_KEYS = new Set(['page', 'per_page', 'includes', 'include', 'sort']);
+const PASSTHROUGH_KEYS = new Set(['page', 'limit', 'expand', 'sort']);
type ParamValue = string | number | boolean | (string | number)[] | undefined;
/**
* Transforms flat SDK params into Ransack-compatible query params.
*
- * - `page`, `per_page`, `includes`, `include`, `sort` pass through unchanged
+ * - `page`, `limit`, `expand`, `sort` pass through unchanged
* - Keys already in `q[...]` format pass through (backward compat)
* - All other keys are wrapped: `name_cont` → `q[name_cont]`
*/
@@ -21,7 +21,7 @@ export function transformListParams(
if (value === undefined) continue;
if (PASSTHROUGH_KEYS.has(key)) {
- // Join arrays for passthrough keys (e.g., includes: ['variants', 'images'] → 'variants,images')
+ // Join arrays for passthrough keys (e.g., expand: ['variants', 'images'] → 'variants,images')
result[key] = Array.isArray(value) ? (value as (string | number)[]).join(',') : value as ParamValue;
continue;
}
diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.ts
index 96c152477e..307fa96f48 100644
--- a/packages/sdk/src/store-client.ts
+++ b/packages/sdk/src/store-client.ts
@@ -108,7 +108,7 @@ export class StoreClient {
*/
get: (
idOrSlug: string,
- params?: { includes?: string },
+ params?: { expand?: string },
options?: RequestOptions
): Promise<StoreProduct> =>
this.request<StoreProduct>('GET', `/products/${idOrSlug}`, {
@@ -152,7 +152,7 @@ export class StoreClient {
*/
get: (
id: string,
- params?: { includes?: string },
+ params?: { expand?: string },
options?: RequestOptions
): Promise<StoreTaxonomy> =>
this.request<StoreTaxonomy>('GET', `/taxonomies/${id}`, {
@@ -179,7 +179,7 @@ export class StoreClient {
*/
get: (
idOrPermalink: string,
- params?: { includes?: string },
+ params?: { expand?: string },
options?: RequestOptions
): Promise<StoreTaxon> =>
this.request<StoreTaxon>('GET', `/taxons/${idOrPermalink}`, {
@@ -225,12 +225,12 @@ export class StoreClient {
/**
* Get a country by ISO code
- * Use `?include=states` to include states for address forms
+ * Use `?expand=states` to expand states for address forms
* @param iso - ISO 3166-1 alpha-2 code (e.g., "US", "DE")
*/
get: (
iso: string,
- params?: { include?: string },
+ params?: { expand?: string },
options?: RequestOptions
): Promise<StoreCountry> =>
this.request<StoreCountry>('GET', `/countries/${iso}`, {
@@ -309,7 +309,7 @@ export class StoreClient {
get: (
marketId: string,
iso: string,
- params?: { include?: string },
+ params?: { expand?: string },
options?: RequestOptions
): Promise<StoreCountry> =>
this.request<StoreCountry>(
@@ -361,7 +361,7 @@ export class StoreClient {
*/
get: (
idOrNumber: string,
- params?: { includes?: string },
+ params?: { expand?: string },
options?: RequestOptions
): Promise<StoreOrder> =>
this.request<StoreOrder>('GET', `/orders/${idOrNumber}`, {
@@ -911,7 +911,7 @@ export class StoreClient {
*/
get: (
id: string,
- params?: { includes?: string },
+ params?: { expand?: string },
options?: RequestOptions
): Promise<StoreWishlist> =>
this.request<StoreWishlist>('GET', `/wishlists/${id}`, {
diff --git a/packages/sdk/src/types/index.ts b/packages/sdk/src/types/index.ts
index cc15b40de4..08515b6a2a 100644
--- a/packages/sdk/src/types/index.ts
+++ b/packages/sdk/src/types/index.ts
@@ -56,9 +56,9 @@ export interface RegisterParams {
// Query params
export interface ListParams {
page?: number;
- per_page?: number;
- /** Associations to include. Accepts array or comma-separated string. */
- includes?: string[] | string;
+ limit?: number;
+ /** Associations to expand. Accepts array or comma-separated string. */
+ expand?: string[] | string;
}
export interface ProductListParams extends ListParams {
diff --git a/packages/sdk/tests/params.test.ts b/packages/sdk/tests/params.test.ts
index c85f2f808d..410599ea2a 100644
--- a/packages/sdk/tests/params.test.ts
+++ b/packages/sdk/tests/params.test.ts
@@ -3,23 +3,18 @@ import { transformListParams } from '../src/params';
describe('transformListParams', () => {
it('passes through pagination params unchanged', () => {
- const result = transformListParams({ page: 2, per_page: 10 });
- expect(result).toEqual({ page: 2, per_page: 10 });
+ const result = transformListParams({ page: 2, limit: 10 });
+ expect(result).toEqual({ page: 2, limit: 10 });
});
- it('passes through includes string unchanged', () => {
- const result = transformListParams({ includes: 'variants,images' });
- expect(result).toEqual({ includes: 'variants,images' });
+ it('passes through expand string unchanged', () => {
+ const result = transformListParams({ expand: 'variants,images' });
+ expect(result).toEqual({ expand: 'variants,images' });
});
- it('joins includes array into comma-separated string', () => {
- const result = transformListParams({ includes: ['variants', 'images'] });
- expect(result).toEqual({ includes: 'variants,images' });
- });
-
- it('passes through include param unchanged', () => {
- const result = transformListParams({ include: 'variants' });
- expect(result).toEqual({ include: 'variants' });
+ it('joins expand array into comma-separated string', () => {
+ const result = transformListParams({ expand: ['variants', 'images'] });
+ expect(result).toEqual({ expand: 'variants,images' });
});
it('passes through sort param unchanged', () => {
@@ -81,8 +76,8 @@ describe('transformListParams', () => {
it('handles a full combined query', () => {
const result = transformListParams({
page: 1,
- per_page: 12,
- includes: 'images,default_variant',
+ limit: 12,
+ expand: 'images,default_variant',
sort: 'created_at desc',
name_cont: 'shirt',
price_gte: 20,
@@ -90,8 +85,8 @@ describe('transformListParams', () => {
});
expect(result).toEqual({
page: 1,
- per_page: 12,
- includes: 'images,default_variant',
+ limit: 12,
+ expand: 'images,default_variant',
sort: 'created_at desc',
'q[name_cont]': 'shirt',
'q[price_gte]': 20,
diff --git a/packages/sdk/tests/products.test.ts b/packages/sdk/tests/products.test.ts
index 4674c7a507..082853b9d7 100644
--- a/packages/sdk/tests/products.test.ts
+++ b/packages/sdk/tests/products.test.ts
@@ -20,7 +20,7 @@ describe('products', () => {
it('passes query parameters', async () => {
const result = await client.store.products.list({
page: 2,
- per_page: 10,
+ limit: 10,
name_cont: 'shirt',
});
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/http_caching.rb b/spree/api/app/controllers/concerns/spree/api/v3/http_caching.rb
index 5da5847428..9723f016b6 100644
--- a/spree/api/app/controllers/concerns/spree/api/v3/http_caching.rb
+++ b/spree/api/app/controllers/concerns/spree/api/v3/http_caching.rb
@@ -69,15 +69,15 @@ module Spree
private
# Build a cache key for a collection
- # Includes: query params, pagination, includes, currency, locale
+ # Includes: query params, pagination, expand, currency, locale
# Strips order to avoid PostgreSQL errors with DISTINCT + subquery ORDER BY expressions
def collection_cache_key(collection)
parts = [
collection.reorder(nil).cache_key_with_version,
- params[:include],
+ params[:expand],
params[:q],
params[:page],
- params[:per_page],
+ params[:limit],
current_currency,
current_locale
]
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/resource_serializer.rb b/spree/api/app/controllers/concerns/spree/api/v3/resource_serializer.rb
index d21f115eeb..009f0aadf0 100644
--- a/spree/api/app/controllers/concerns/spree/api/v3/resource_serializer.rb
+++ b/spree/api/app/controllers/concerns/spree/api/v3/resource_serializer.rb
@@ -23,17 +23,17 @@ module Spree
store: current_store,
user: current_user,
locale: current_locale,
- includes: include_list
+ expand: expand_list
}
end
- # Parse include parameter into list
- # Supports: ?include=variants,images or ?includes=variants,images
- def include_list
- include_param = params[:include].presence || params[:includes].presence
- return [] unless include_param
+ # Parse expand parameter into list
+ # Supports: ?expand=variants,images
+ def expand_list
+ expand_param = params[:expand].presence
+ return [] unless expand_param
- include_param.to_s.split(',').map(&:strip)
+ expand_param.to_s.split(',').map(&:strip)
end
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/resource_controller.rb b/spree/api/app/controllers/spree/api/v3/resource_controller.rb
index 308c4cfd9c..4e5e387fc2 100644
--- a/spree/api/app/controllers/spree/api/v3/resource_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/resource_controller.rb
@@ -127,7 +127,7 @@ module Spree
end
def limit
- limit_param = params[:per_page]&.to_i || params[:limit]&.to_i || 25
+ limit_param = params[:limit]&.to_i || 25
[limit_param, 100].min # Max 100 per page
end
diff --git a/spree/api/app/controllers/spree/api/v3/store/markets_controller.rb b/spree/api/app/controllers/spree/api/v3/store/markets_controller.rb
index 03c9a03a57..34946481c1 100644
--- a/spree/api/app/controllers/spree/api/v3/store/markets_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/markets_controller.rb
@@ -33,7 +33,7 @@ module Spree
private
def serialize_market(market)
- Spree.api.market_serializer.new(market, params: serializer_params.merge(includes: include_list + ['countries'])).to_h
+ Spree.api.market_serializer.new(market, params: serializer_params.merge(expand: expand_list + ['countries'])).to_h
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb
index 295e6daa5f..a1d5de2dc5 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb
@@ -33,7 +33,7 @@ module Spree
many :orders,
resource: Spree.api.admin_order_serializer,
- if: proc { params[:includes]&.include?('orders') }
+ if: proc { params[:expand]&.include?('orders') }
# TODO: Add store_credits association when Admin API is implemented
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
index 117d504ab4..0d97822c86 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
@@ -36,7 +36,7 @@ module Spree
one :user,
resource: Spree.api.admin_customer_serializer,
- if: proc { params[:includes]&.include?('user') }
+ if: proc { params[:expand]&.include?('user') }
# TODO: Add adjustments associations when Admin API is implemented
end
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 b8f0fede72..855955a35b 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
@@ -26,20 +26,20 @@ module Spree
# Admin uses admin variant serializer
many :variants,
resource: Spree.api.admin_variant_serializer,
- if: proc { params[:includes]&.include?('variants') }
+ if: proc { params[:expand]&.include?('variants') }
one :default_variant,
resource: Spree.api.admin_variant_serializer,
- if: proc { params[:includes]&.include?('default_variant') }
+ if: proc { params[:expand]&.include?('default_variant') }
one :master,
key: :master_variant,
resource: Spree.api.admin_variant_serializer,
- if: proc { params[:includes]&.include?('master_variant') }
+ if: proc { params[:expand]&.include?('master_variant') }
many :metafields,
resource: Spree.api.admin_metafield_serializer,
- if: proc { params[:includes]&.include?('metafields') }
+ if: proc { params[:expand]&.include?('metafields') }
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/taxon_serializer.rb
index 090d9c58ad..c8d92bda1b 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/taxon_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/taxon_serializer.rb
@@ -12,7 +12,7 @@ module Spree
many :metafields,
resource: Spree.api.admin_metafield_serializer,
- if: proc { params[:includes]&.include?('metafields') }
+ if: proc { params[:expand]&.include?('metafields') }
end
end
end
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
index 3f50978a06..b822865ae5 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/taxonomy_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/taxonomy_serializer.rb
@@ -7,7 +7,7 @@ module Spree
class TaxonomySerializer < V3::TaxonomySerializer
many :metafields,
resource: Spree.api.admin_metafield_serializer,
- if: proc { params[:includes]&.include?('metafields') }
+ if: proc { params[:expand]&.include?('metafields') }
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb
index 719358c083..7117a5b263 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/variant_serializer.rb
@@ -30,11 +30,11 @@ module Spree
# All prices for this variant (for admin management)
many :prices,
resource: Spree.api.admin_price_serializer,
- if: proc { params[:includes]&.include?('prices') }
+ if: proc { params[:expand]&.include?('prices') }
many :metafields,
resource: Spree.api.admin_metafield_serializer,
- if: proc { params[:includes]&.include?('metafields') }
+ if: proc { params[:expand]&.include?('metafields') }
# TODO: Add stock_items association when Admin API is implemented
end
diff --git a/spree/api/app/serializers/spree/api/v3/base_serializer.rb b/spree/api/app/serializers/spree/api/v3/base_serializer.rb
index 09d056a099..43e6383e19 100644
--- a/spree/api/app/serializers/spree/api/v3/base_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/base_serializer.rb
@@ -33,24 +33,24 @@ module Spree
params[:locale]
end
- def includes
- @includes ||= Array(params[:includes] || [])
+ def expands
+ @expands ||= Array(params[:expand] || [])
end
- # Check if an association should be included
- def include?(name)
- includes.include?(name.to_s)
+ # Check if an association should be expanded
+ def expand?(name)
+ expands.include?(name.to_s)
end
- # Get nested includes for a given parent
- def nested_includes_for(parent)
+ # Get nested expands for a given parent
+ def nested_expands_for(parent)
prefix = "#{parent}."
- includes.select { |i| i.start_with?(prefix) }.map { |i| i.sub(prefix, '') }
+ expands.select { |i| i.start_with?(prefix) }.map { |i| i.sub(prefix, '') }
end
# Build nested params for child serializers
def nested_params(parent = nil)
- params.merge(includes: parent ? nested_includes_for(parent) : [])
+ params.merge(expand: parent ? nested_expands_for(parent) : [])
end
# Returns price for a variant using full Price List resolution
diff --git a/spree/api/app/serializers/spree/api/v3/country_serializer.rb b/spree/api/app/serializers/spree/api/v3/country_serializer.rb
index f41820acad..d9cf750f81 100644
--- a/spree/api/app/serializers/spree/api/v3/country_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/country_serializer.rb
@@ -12,9 +12,9 @@ module Spree
many :states,
resource: Spree.api.state_serializer,
- if: proc { params[:includes]&.include?('states') }
+ if: proc { params[:expand]&.include?('states') }
- attribute :market, if: proc { params[:includes]&.include?('market') } do |country|
+ attribute :market, if: proc { params[:expand]&.include?('market') } do |country|
m = country.current_market
m ? Spree.api.market_serializer.new(m, params: params).to_h : nil
end
diff --git a/spree/api/app/serializers/spree/api/v3/market_serializer.rb b/spree/api/app/serializers/spree/api/v3/market_serializer.rb
index a6fc96f320..fe9ed0b6f0 100644
--- a/spree/api/app/serializers/spree/api/v3/market_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/market_serializer.rb
@@ -16,7 +16,7 @@ module Spree
many :countries,
resource: Spree.api.country_serializer,
- if: proc { include?(:countries) }
+ if: proc { expand?(:countries) }
end
end
end
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 6ce6884f50..598fd35472 100644
--- a/spree/api/app/serializers/spree/api/v3/product_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/product_serializer.rb
@@ -71,37 +71,37 @@ module Spree
many :variant_images,
key: :images,
resource: Spree.api.image_serializer,
- if: proc { params[:includes]&.include?('images') }
+ if: proc { params[:expand]&.include?('images') }
many :variants,
resource: Spree.api.variant_serializer,
- if: proc { params[:includes]&.include?('variants') }
+ if: proc { params[:expand]&.include?('variants') }
one :default_variant,
resource: Spree.api.variant_serializer,
- if: proc { params[:includes]&.include?('default_variant') }
+ if: proc { params[:expand]&.include?('default_variant') }
one :master,
key: :master_variant,
resource: Spree.api.variant_serializer,
- if: proc { params[:includes]&.include?('master_variant') }
+ if: proc { params[:expand]&.include?('master_variant') }
many :option_types,
resource: Spree.api.option_type_serializer,
- if: proc { params[:includes]&.include?('option_types') }
+ if: proc { params[:expand]&.include?('option_types') }
many :taxons,
proc { |taxons, params|
taxons.select { |t| t.taxonomy.store_id == params[:store].id }
},
resource: Spree.api.taxon_serializer,
- if: proc { params[:includes]&.include?('taxons') },
- params: { includes: [] }
+ if: proc { params[:expand]&.include?('taxons') },
+ params: { expand: [] }
many :public_metafields,
key: :metafields,
resource: Spree.api.metafield_serializer,
- if: proc { params[:includes]&.include?('metafields') }
+ if: proc { params[:expand]&.include?('metafields') }
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/taxon_serializer.rb b/spree/api/app/serializers/spree/api/v3/taxon_serializer.rb
index 828b7ba590..6fcaeebf4e 100644
--- a/spree/api/app/serializers/spree/api/v3/taxon_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/taxon_serializer.rb
@@ -51,27 +51,27 @@ module Spree
end
# Conditional associations
- # Note: We pass empty includes to nested taxons to prevent infinite recursion
+ # Note: We pass empty expand to nested taxons to prevent infinite recursion
# (e.g., ancestors trying to load their own ancestors)
one :parent,
resource: Spree.api.taxon_serializer,
- if: proc { params[:includes]&.include?('parent') },
- params: { includes: [] }
+ if: proc { params[:expand]&.include?('parent') },
+ params: { expand: [] }
many :children,
resource: Spree.api.taxon_serializer,
- if: proc { params[:includes]&.include?('children') },
- params: { includes: [] }
+ if: proc { params[:expand]&.include?('children') },
+ params: { expand: [] }
many :ancestors,
resource: Spree.api.taxon_serializer,
- if: proc { params[:includes]&.include?('ancestors') },
- params: { includes: [] }
+ if: proc { params[:expand]&.include?('ancestors') },
+ params: { expand: [] }
many :public_metafields,
key: :metafields,
resource: Spree.api.metafield_serializer,
- if: proc { params[:includes]&.include?('metafields') }
+ if: proc { params[:expand]&.include?('metafields') }
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/taxonomy_serializer.rb b/spree/api/app/serializers/spree/api/v3/taxonomy_serializer.rb
index 9cba57e6a6..9c6d868e80 100644
--- a/spree/api/app/serializers/spree/api/v3/taxonomy_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/taxonomy_serializer.rb
@@ -12,21 +12,21 @@ module Spree
end
# Conditional associations
- # Note: We pass empty includes to nested taxons to prevent infinite recursion
+ # Note: We pass empty expand to nested taxons to prevent infinite recursion
one :root,
resource: Spree.api.taxon_serializer,
- if: proc { params[:includes]&.include?('root') },
- params: { includes: [] }
+ if: proc { params[:expand]&.include?('root') },
+ params: { expand: [] }
many :taxons,
resource: Spree.api.taxon_serializer,
- if: proc { params[:includes]&.include?('taxons') },
- params: { includes: [] }
+ if: proc { params[:expand]&.include?('taxons') },
+ params: { expand: [] }
many :public_metafields,
key: :metafields,
resource: Spree.api.metafield_serializer,
- if: proc { params[:includes]&.include?('metafields') }
+ if: proc { params[:expand]&.include?('metafields') }
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/variant_serializer.rb b/spree/api/app/serializers/spree/api/v3/variant_serializer.rb
index 7d594d07d6..fbc888cbc3 100644
--- a/spree/api/app/serializers/spree/api/v3/variant_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/variant_serializer.rb
@@ -72,14 +72,14 @@ module Spree
# Conditional associations
many :images,
resource: Spree.api.image_serializer,
- if: proc { params[:includes]&.include?('images') }
+ if: proc { params[:expand]&.include?('images') }
many :option_values, resource: Spree.api.option_value_serializer
many :public_metafields,
key: :metafields,
resource: Spree.api.metafield_serializer,
- if: proc { params[:includes]&.include?('metafields') }
+ if: proc { params[:expand]&.include?('metafields') }
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/wishlist_serializer.rb b/spree/api/app/serializers/spree/api/v3/wishlist_serializer.rb
index 730129bc75..a0fdb99147 100644
--- a/spree/api/app/serializers/spree/api/v3/wishlist_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/wishlist_serializer.rb
@@ -18,7 +18,7 @@ module Spree
many :wished_items,
key: :items,
resource: Spree.api.wished_item_serializer,
- if: proc { params[:includes]&.include?('items') }
+ if: proc { params[:expand]&.include?('items') }
end
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/store/products_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/products_controller_spec.rb
index a06b5ced93..3b1ae014a5 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/products_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/products_controller_spec.rb
@@ -35,7 +35,7 @@ RSpec.describe Spree::Api::V3::Store::ProductsController, type: :controller do
end
it 'returns pagination metadata' do
- get :index, params: { page: 1, per_page: 1 }
+ get :index, params: { page: 1, limit: 1 }
expect(response).to have_http_status(:ok)
expect(json_response['data'].size).to eq(1)
@@ -47,8 +47,8 @@ RSpec.describe Spree::Api::V3::Store::ProductsController, type: :controller do
)
end
- it 'respects max per_page limit' do
- get :index, params: { per_page: 500 }
+ it 'respects max limit limit' do
+ get :index, params: { limit: 500 }
expect(json_response['meta']['limit']).to eq(100)
end
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/taxons/products_controller_spec.rb
index 291e187f96..45a18ecf0a 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/taxons/products_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/taxons/products_controller_spec.rb
@@ -69,7 +69,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, per_page: 2, page: 1 }
+ get :index, params: { taxon_id: taxon.permalink, limit: 2, page: 1 }
expect(json_response['data'].size).to eq(2)
expect(json_response['meta']['page']).to eq(1)
diff --git a/spree/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb
index 23944492db..dd34cf8951 100644
--- a/spree/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/store/taxons_controller_spec.rb
@@ -144,9 +144,9 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
expect(json_response).not_to include('lft', 'rgt')
end
- context 'with includes=ancestors' do
+ context 'with expand=ancestors' do
it 'returns ancestors for breadcrumbs' do
- get :show, params: { id: grandchild_taxon.prefixed_id, includes: 'ancestors' }
+ get :show, params: { id: grandchild_taxon.prefixed_id, expand: 'ancestors' }
expect(response).to have_http_status(:ok)
expect(json_response['ancestors']).to be_an(Array)
@@ -157,16 +157,16 @@ RSpec.describe Spree::Api::V3::Store::TaxonsController, type: :controller do
it 'returns empty ancestors for root taxon' do
root_taxon = taxonomy.root
- get :show, params: { id: root_taxon.prefixed_id, includes: 'ancestors' }
+ get :show, params: { id: root_taxon.prefixed_id, expand: 'ancestors' }
expect(response).to have_http_status(:ok)
expect(json_response['ancestors']).to eq([])
end
end
- context 'with includes=children' do
+ context 'with expand=children' do
it 'returns children' do
- get :show, params: { id: taxon.prefixed_id, includes: 'children' }
+ get :show, params: { id: taxon.prefixed_id, expand: 'children' }
expect(response).to have_http_status(:ok)
expect(json_response['children']).to be_an(Array)
diff --git a/spree/api/spec/integration/spree/api/v3/store/addresses_spec.rb b/spree/api/spec/integration/spree/api/v3/store/addresses_spec.rb
index c267759338..215bd1782f 100644
--- a/spree/api/spec/integration/spree/api/v3/store/addresses_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/addresses_spec.rb
@@ -25,7 +25,7 @@ RSpec.describe 'Addresses API', type: :request, swagger_doc: 'api-reference/stor
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: true
parameter name: :page, in: :query, type: :integer, required: false
- parameter name: :per_page, in: :query, type: :integer, required: false
+ parameter name: :limit, in: :query, type: :integer, required: false
response '200', 'addresses found' do
let(:'x-spree-api-key') { api_key.token }
diff --git a/spree/api/spec/integration/spree/api/v3/store/countries_spec.rb b/spree/api/spec/integration/spree/api/v3/store/countries_spec.rb
index 61c9729d12..c4dd996dbd 100644
--- a/spree/api/spec/integration/spree/api/v3/store/countries_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/countries_spec.rb
@@ -18,7 +18,7 @@ RSpec.describe 'Countries API', type: :request, swagger_doc: 'api-reference/stor
tags 'Internationalization'
produces 'application/json'
security [api_key: []]
- description 'Returns countries available in the store. Use ?include=market to include market details (currency, locale, tax_inclusive).'
+ description 'Returns countries available in the store. Use ?expand=market to include market details (currency, locale, tax_inclusive).'
sdk_example <<~JS
const countries = await client.store.countries.list()
@@ -67,7 +67,7 @@ RSpec.describe 'Countries API', type: :request, swagger_doc: 'api-reference/stor
tags 'Internationalization'
produces 'application/json'
security [api_key: []]
- description 'Returns a single country by ISO code. Supports ?include=states for address forms and ?include=market for market details.'
+ description 'Returns a single country by ISO code. Supports ?expand=states for address forms and ?expand=market for market details.'
sdk_example <<~JS
const country = await client.store.countries.get('US')
@@ -109,10 +109,10 @@ RSpec.describe 'Countries API', type: :request, swagger_doc: 'api-reference/stor
end
end
- # Non-swagger tests for ?include functionality
- describe 'GET /api/v3/store/countries/:iso?include=states' do
+ # Non-swagger tests for ?expand functionality
+ describe 'GET /api/v3/store/countries/:iso?expand=states' do
it 'includes states when requested' do
- get "/api/v3/store/countries/US?include=states", headers: { 'x-spree-api-key' => api_key.token }
+ get "/api/v3/store/countries/US?expand=states", headers: { 'x-spree-api-key' => api_key.token }
expect(response).to have_http_status(:ok)
data = JSON.parse(response.body)
@@ -122,9 +122,9 @@ RSpec.describe 'Countries API', type: :request, swagger_doc: 'api-reference/stor
end
end
- describe 'GET /api/v3/store/countries/:iso?include=market' do
+ describe 'GET /api/v3/store/countries/:iso?expand=market' do
it 'includes market details when requested' do
- get "/api/v3/store/countries/US?include=market", headers: { 'x-spree-api-key' => api_key.token }
+ get "/api/v3/store/countries/US?expand=market", headers: { 'x-spree-api-key' => api_key.token }
expect(response).to have_http_status(:ok)
data = JSON.parse(response.body)
diff --git a/spree/api/spec/integration/spree/api/v3/store/credit_cards_spec.rb b/spree/api/spec/integration/spree/api/v3/store/credit_cards_spec.rb
index 2017c7225b..689e6fb841 100644
--- a/spree/api/spec/integration/spree/api/v3/store/credit_cards_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/credit_cards_spec.rb
@@ -23,7 +23,7 @@ RSpec.describe 'Credit Cards API', type: :request, swagger_doc: 'api-reference/s
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: true
parameter name: :page, in: :query, type: :integer, required: false
- parameter name: :per_page, in: :query, type: :integer, required: false
+ parameter name: :limit, in: :query, type: :integer, required: false
response '200', 'credit cards found' do
let(:'x-spree-api-key') { api_key.token }
diff --git a/spree/api/spec/integration/spree/api/v3/store/customer_orders_spec.rb b/spree/api/spec/integration/spree/api/v3/store/customer_orders_spec.rb
index f4fe43260b..fdcaa4418e 100644
--- a/spree/api/spec/integration/spree/api/v3/store/customer_orders_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/customer_orders_spec.rb
@@ -18,7 +18,7 @@ RSpec.describe 'Customer Orders API', type: :request, swagger_doc: 'api-referenc
sdk_example <<~JS
const orders = await client.store.customer.orders.list({
page: 1,
- per_page: 25,
+ limit: 25,
}, {
bearerToken: '<token>',
})
@@ -27,7 +27,7 @@ RSpec.describe 'Customer Orders API', type: :request, swagger_doc: 'api-referenc
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: true
parameter name: :page, in: :query, type: :integer, required: false
- parameter name: :per_page, in: :query, type: :integer, required: false
+ parameter name: :limit, in: :query, type: :integer, required: false
parameter name: 'q[state_eq]', in: :query, type: :string, required: false,
description: 'Filter by order state'
parameter name: 'q[completed_at_gte]', in: :query, type: :string, required: false,
diff --git a/spree/api/spec/integration/spree/api/v3/store/gift_cards_spec.rb b/spree/api/spec/integration/spree/api/v3/store/gift_cards_spec.rb
index 250525481a..7381c90e97 100644
--- a/spree/api/spec/integration/spree/api/v3/store/gift_cards_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/gift_cards_spec.rb
@@ -23,7 +23,7 @@ RSpec.describe 'Gift Cards API', type: :request, swagger_doc: 'api-reference/sto
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: true
parameter name: :page, in: :query, type: :integer, required: false
- parameter name: :per_page, in: :query, type: :integer, required: false
+ parameter name: :limit, in: :query, type: :integer, required: false
response '200', 'gift cards found' do
let(:'x-spree-api-key') { api_key.token }
diff --git a/spree/api/spec/integration/spree/api/v3/store/markets_spec.rb b/spree/api/spec/integration/spree/api/v3/store/markets_spec.rb
index 9eb5d46198..864501a137 100644
--- a/spree/api/spec/integration/spree/api/v3/store/markets_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/markets_spec.rb
@@ -189,7 +189,7 @@ RSpec.describe 'Markets API', type: :request, swagger_doc: 'api-reference/store.
tags 'Markets'
produces 'application/json'
security [api_key: []]
- description 'Returns a single country by ISO code within a market. Supports ?include=states for address forms.'
+ description 'Returns a single country by ISO code within a market. Supports ?expand=states for address forms.'
sdk_example <<~JS
const country = await client.store.markets.countries.get('mkt_xxx', 'DE')
diff --git a/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb b/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb
index 1e6ffbc66b..3c05fedc8e 100644
--- a/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/orders_spec.rb
@@ -17,7 +17,7 @@ RSpec.describe 'Orders API', type: :request, swagger_doc: 'api-reference/store.y
sdk_example <<~JS
const order = await client.store.orders.get('or_abc123', {
- includes: 'line_items,shipments',
+ expand: 'line_items,shipments',
}, {
bearerToken: '<token>',
})
@@ -29,8 +29,8 @@ RSpec.describe 'Orders API', type: :request, swagger_doc: 'api-reference/store.y
description: 'Order ID (prefixed) or order number'
parameter name: :order_token, in: :query, type: :string, required: false,
description: 'Order token for guest access'
- parameter name: :includes, in: :query, type: :string, required: false,
- description: 'Include associations (line_items, shipments, payments)'
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Expand associations (line_items, shipments, payments)'
response '200', 'order found (authenticated)' do
let(:'x-spree-api-key') { api_key.token }
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 5bd92dbe81..3e10872a92 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
@@ -33,13 +33,13 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
sdk_example <<~JS
const products = await client.store.products.list({
page: 1,
- per_page: 25,
+ limit: 25,
sort: 'price asc',
name_cont: 'shirt',
price_gte: 20,
price_lte: 100,
with_option_value_ids: ['optval_abc', 'optval_def'],
- includes: ['variants', 'images'],
+ expand: ['variants', 'images'],
})
JS
@@ -47,7 +47,7 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
description: 'Publishable API key'
parameter name: :page, in: :query, type: :integer, required: false,
description: 'Page number (default: 1)'
- parameter name: :per_page, in: :query, type: :integer, required: false,
+ parameter name: :limit, in: :query, type: :integer, required: false,
description: 'Number of items per page (default: 25, max: 100)'
parameter name: :sort, in: :query, type: :string, required: false,
description: 'Sort order. Values: price asc, price desc, best_selling, name asc, name desc, available_on desc, available_on asc'
@@ -63,8 +63,8 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
description: 'Filter by option value prefix IDs (e.g., optval_abc). Pass multiple values for OR logic.'
parameter name: 'q[in_stock]', in: :query, type: :boolean, required: false,
description: 'Filter to only in-stock products'
- parameter name: :includes, in: :query, type: :string, required: false,
- description: 'Comma-separated associations to include (variants, images, taxons, option_types)'
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Comma-separated associations to expand (variants, images, taxons, option_types)'
response '200', 'products found' do
let(:'x-spree-api-key') { api_key.token }
@@ -105,7 +105,7 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
sdk_example <<~JS
const product = await client.store.products.get('spree-tote', {
- includes: ['variants', 'images'],
+ expand: ['variants', 'images'],
})
JS
@@ -113,8 +113,8 @@ RSpec.describe 'Products API', type: :request, swagger_doc: 'api-reference/store
description: 'Publishable API key'
parameter name: :id, in: :path, type: :string, required: true,
description: 'Product slug (e.g., spree-tote) or prefix ID (e.g., product_abc123)'
- parameter name: :includes, in: :query, type: :string, required: false,
- description: 'Comma-separated associations to include'
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Comma-separated associations to expand'
response '200', 'product found by slug' do
let(:'x-spree-api-key') { api_key.token }
diff --git a/spree/api/spec/integration/spree/api/v3/store/shipments_spec.rb b/spree/api/spec/integration/spree/api/v3/store/shipments_spec.rb
index c5066fc0d0..f7e3e0220e 100644
--- a/spree/api/spec/integration/spree/api/v3/store/shipments_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/shipments_spec.rb
@@ -68,8 +68,8 @@ RSpec.describe 'Shipments API', type: :request, swagger_doc: 'api-reference/stor
parameter name: :order_id, in: :path, type: :string, required: true
parameter name: :id, in: :path, type: :string, required: true, description: 'Shipment ID'
parameter name: :token, in: :query, type: :string, required: false, description: 'Order token for guest access'
- parameter name: :includes, in: :query, type: :string, required: false,
- description: 'Include shipping_rates'
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Expand shipping_rates'
response '200', 'shipment found' do
let(:'x-spree-api-key') { api_key.token }
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
index c0dbea5691..eba712c8ac 100644
--- a/spree/api/spec/integration/spree/api/v3/store/taxonomies_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/taxonomies_spec.rb
@@ -20,15 +20,15 @@ RSpec.describe 'Taxonomies API', type: :request, swagger_doc: 'api-reference/sto
sdk_example <<~JS
const taxonomies = await client.store.taxonomies.list({
page: 1,
- per_page: 25,
+ 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: :per_page, in: :query, type: :integer, required: false
- parameter name: :includes, in: :query, type: :string, required: false,
- description: 'Include root taxon'
+ parameter name: :limit, in: :query, type: :integer, required: false
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Expand root taxon'
response '200', 'taxonomies found' do
let(:'x-spree-api-key') { api_key.token }
@@ -64,15 +64,15 @@ RSpec.describe 'Taxonomies API', type: :request, swagger_doc: 'api-reference/sto
sdk_example <<~JS
const taxonomy = await client.store.taxonomies.get('taxonomy_abc123', {
- includes: 'taxons',
+ 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: :includes, in: :query, type: :string, required: false,
- description: 'Include taxons'
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Expand taxons'
response '200', 'taxonomy found' do
let(:'x-spree-api-key') { api_key.token }
diff --git a/spree/api/spec/integration/spree/api/v3/store/taxons_spec.rb b/spree/api/spec/integration/spree/api/v3/store/taxons_spec.rb
index 83d6cb9b69..686ce6d24c 100644
--- a/spree/api/spec/integration/spree/api/v3/store/taxons_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/taxons_spec.rb
@@ -24,13 +24,13 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
sdk_example <<~JS
const taxons = await client.store.taxons.list({
page: 1,
- per_page: 25,
+ 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: :per_page, in: :query, type: :integer, required: false
+ parameter name: :limit, in: :query, type: :integer, required: false
parameter name: 'q[name_cont]', in: :query, type: :string, required: false,
description: 'Filter by name'
@@ -72,15 +72,15 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
sdk_example <<~JS
const taxon = await client.store.taxons.get('categories/clothing/shirts', {
- includes: 'children,products',
+ expand: 'children,products',
})
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)'
- parameter name: :includes, in: :query, type: :string, required: false,
- description: 'Include associations (children, products, parent)'
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Expand associations (children, products, parent)'
response '200', 'taxon found by permalink' do
let(:'x-spree-api-key') { api_key.token }
@@ -145,7 +145,7 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
sdk_example <<~JS
const products = await client.store.taxons.products.list('categories/clothing', {
page: 1,
- per_page: 25,
+ limit: 25,
sort: 'price asc',
with_option_value_ids: ['optval_abc'],
})
@@ -156,7 +156,7 @@ RSpec.describe 'Taxons API', type: :request, swagger_doc: 'api-reference/store.y
description: 'Taxon permalink or prefix ID'
parameter name: :page, in: :query, type: :integer, required: false,
description: 'Page number (default: 1)'
- parameter name: :per_page, in: :query, type: :integer, required: false,
+ parameter name: :limit, in: :query, type: :integer, required: false,
description: 'Number of items per page (default: 25, max: 100)'
parameter name: :sort, in: :query, type: :string, required: false,
description: 'Sort order. Values: price asc, price desc, best_selling, name asc, name desc, available_on desc, available_on asc'
diff --git a/spree/api/spec/integration/spree/api/v3/store/wishlists_spec.rb b/spree/api/spec/integration/spree/api/v3/store/wishlists_spec.rb
index 7192670211..511a9ee4f0 100644
--- a/spree/api/spec/integration/spree/api/v3/store/wishlists_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/wishlists_spec.rb
@@ -26,7 +26,7 @@ RSpec.describe 'Wishlists API', type: :request, swagger_doc: 'api-reference/stor
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: true
parameter name: :page, in: :query, type: :integer, required: false
- parameter name: :per_page, in: :query, type: :integer, required: false
+ parameter name: :limit, in: :query, type: :integer, required: false
response '200', 'wishlists found' do
let(:'x-spree-api-key') { api_key.token }
@@ -116,7 +116,7 @@ RSpec.describe 'Wishlists API', type: :request, swagger_doc: 'api-reference/stor
sdk_example <<~JS
const wishlist = await client.store.wishlists.get('wl_abc123', {
- includes: 'wished_items',
+ expand: 'wished_items',
}, {
bearerToken: '<token>',
})
@@ -125,8 +125,8 @@ RSpec.describe 'Wishlists API', type: :request, swagger_doc: 'api-reference/stor
parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
parameter name: 'Authorization', in: :header, type: :string, required: true
parameter name: :id, in: :path, type: :string, required: true
- parameter name: :includes, in: :query, type: :string, required: false,
- description: 'Include wished_items'
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Expand wished_items'
response '200', 'wishlist found' do
let(:'x-spree-api-key') { api_key.token }
diff --git a/spree/api/spec/serializers/spree/api/v3/product_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/product_serializer_spec.rb
index a77086d583..73f9504d9e 100644
--- a/spree/api/spec/serializers/spree/api/v3/product_serializer_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/product_serializer_spec.rb
@@ -60,7 +60,7 @@ RSpec.describe Spree::Api::V3::ProductSerializer do
end
it 'includes only public metafields with include param' do
- result = described_class.new(product, params: base_params.merge(includes: ['metafields'])).to_h
+ result = described_class.new(product, params: base_params.merge(expand: ['metafields'])).to_h
expect(result['metafields'].length).to eq(1)
expect(result['metafields'].first['value']).to eq('public')
end
@@ -86,7 +86,7 @@ RSpec.describe Spree::Api::V3::Admin::ProductSerializer do
create(:metafield, resource: product, metafield_definition: public_def, value: 'public')
create(:metafield, resource: product, metafield_definition: private_def, value: 'private')
- result = described_class.new(product, params: base_params.merge(includes: ['metafields'])).to_h
+ result = described_class.new(product, params: base_params.merge(expand: ['metafields'])).to_h
expect(result['metafields'].length).to eq(2)
expect(result['metafields']).to all(have_key('display_on'))
end
diff --git a/spree/api/spec/serializers/spree/api/v3/variant_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/variant_serializer_spec.rb
index f219c5c6a0..79f4732360 100644
--- a/spree/api/spec/serializers/spree/api/v3/variant_serializer_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/variant_serializer_spec.rb
@@ -64,7 +64,7 @@ RSpec.describe Spree::Api::V3::Admin::VariantSerializer do
end
it 'includes prices array when included' do
- result = described_class.new(variant, params: base_params.merge(includes: ['prices'])).to_h
+ result = described_class.new(variant, params: base_params.merge(expand: ['prices'])).to_h
expect(result['prices']).to be_an(Array)
end
end