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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Admin API: integration tests, OpenAPI spec, and SDK generation for all catalog endpoints
Damian Legawiecc2c841f9ca68
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yamlnew file mode 100644index 0000000000..c8153c4281--- /dev/null+++ b/docs/api-reference/admin.yaml@@ -0,0 +1,3969 @@+---+openapi: 3.0.3+info:+ title: Admin API+ contact:+ name: Spree Commerce+ url: https://spreecommerce.org+ email: [email protected]+ description: |+ Spree Admin API v3 - Administrative API for managing products, orders, and store settings.++ ## Authentication++ The Admin API requires a secret API key passed in the `x-spree-api-key` header.+ Secret API keys can be generated in the Spree admin dashboard.++ ## Response Format++ All responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.+ Single resource endpoints return a flat JSON object.++ ## Prefixed IDs++ All resources use Stripe-style prefixed IDs (e.g., `prod_86Rf07xd4z`, `variant_k5nR8xLq`).+ These IDs must be used in all API requests.++ ## Error Handling++ Errors return a consistent format:+ ```json+ {+ "error": {+ "code": "validation_error",+ "message": "Validation failed",+ "details": { "name": ["can't be blank"] }+ }+ }+ ```+ version: v3+paths:+ "/api/v3/admin/products/{product_id}/assets":+ get:+ summary: List product assets+ tags:+ - Assets+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a paginated list of assets (images) for a product.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: product_id+ in: path+ required: true+ description: Product prefixed ID+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Number of records per page+ schema:+ type: integer+ responses:+ '200':+ description: assets found+ content:+ application/json:+ example:+ data:+ - id: asset_UkLWZg9DAJ+ viewable_id: variant_UkLWZg9DAJ+ type:+ viewable_type: Spree::Variant+ position: 1+ alt:+ created_at: '2026-03-06T19:22:55.186Z'+ updated_at: '2026-03-06T19:22:55.193Z'+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ post:+ summary: Create an asset+ tags:+ - Assets+ security:+ - api_key: []+ bearer_auth: []+ description: Creates a new asset (image) for a product.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: product_id+ in: path+ required: true+ description: Product prefixed ID+ schema:+ type: string+ responses:+ '422':+ description: validation error (attachment required)+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Attachment can't be blank+ details:+ attachment:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ alt:+ type: string+ example: Product front view+ position:+ type: integer+ example: 1+ type:+ type: string+ example: Spree::Image+ description: Asset type (defaults to Spree::Image)+ viewable_type:+ type: string+ description: Polymorphic viewable type+ viewable_id:+ type: string+ description: Polymorphic viewable ID+ "/api/v3/admin/products/{product_id}/assets/{id}":+ patch:+ summary: Update an asset+ tags:+ - Assets+ security:+ - api_key: []+ bearer_auth: []+ description: Updates an asset. Only provided fields are updated.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: product_id+ in: path+ required: true+ description: Product prefixed ID+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Asset prefixed ID+ schema:+ type: string+ responses:+ '200':+ description: asset updated+ content:+ application/json:+ example:+ id: asset_UkLWZg9DAJ+ viewable_id: variant_UkLWZg9DAJ+ type:+ viewable_type: Spree::Variant+ position: 1+ alt: Updated alt text+ created_at: '2026-03-06T19:22:55.988Z'+ updated_at: '2026-03-06T19:22:56.288Z'+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ alt:+ type: string+ example: Updated alt text+ position:+ type: integer+ example: 2+ delete:+ summary: Delete an asset+ tags:+ - Assets+ security:+ - api_key: []+ bearer_auth: []+ description: Deletes an asset from a product.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: product_id+ in: path+ required: true+ description: Product prefixed ID+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Asset prefixed ID+ schema:+ type: string+ responses:+ '204':+ description: asset deleted+ "/api/v3/admin/option_types":+ get:+ summary: List option types+ tags:+ - Option Types+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a paginated list of option types.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Number of records per page+ schema:+ type: integer+ - name: q[name_cont]+ in: query+ required: false+ description: Filter by name (contains)+ schema:+ type: string+ responses:+ '200':+ description: option types found+ content:+ application/json:+ example:+ data:+ - id: opt_UkLWZg9DAJ+ name: foo-size-1+ presentation: Size+ position: 1+ filterable: true+ option_values: []+ 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/AdminOptionType"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ '401':+ description: unauthorized+ content:+ application/json:+ example:+ error:+ code: invalid_token+ message: Valid secret API key required+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ post:+ summary: Create an option type+ tags:+ - Option Types+ security:+ - api_key: []+ bearer_auth: []+ description: |+ Creates a new option type. Supports nested option values.++ Option values can be provided inline and will be created or updated by name.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ responses:+ '201':+ description: option type created+ content:+ application/json:+ example:+ id: opt_gbHJdmfrXB+ name: material+ presentation: Material+ position: 2+ filterable: true+ option_values: []+ schema:+ "$ref": "#/components/schemas/AdminOptionType"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank and Presentation can't be blank+ details:+ name:+ - can't be blank+ presentation:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ example: color+ presentation:+ type: string+ example: Color+ position:+ type: integer+ example: 1+ filterable:+ type: boolean+ example: true+ option_values:+ type: array+ items:+ type: object+ properties:+ name:+ type: string+ example: red+ presentation:+ type: string+ example: Red+ position:+ type: integer+ required:+ - name+ - presentation+ "/api/v3/admin/option_types/{id}":+ get:+ summary: Get an option type+ tags:+ - Option Types+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a single option type by prefixed ID, including its option+ values.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Option type prefixed ID+ schema:+ type: string+ responses:+ '200':+ description: option type found+ content:+ application/json:+ example:+ id: opt_UkLWZg9DAJ+ name: foo-size-5+ presentation: Size+ position: 1+ filterable: true+ option_values: []+ schema:+ "$ref": "#/components/schemas/AdminOptionType"+ '404':+ description: option type not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Couldn't find Spree::OptionType with 'id'=245546638656678833+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update an option type+ tags:+ - Option Types+ security:+ - api_key: []+ bearer_auth: []+ description: Updates an option type. Supports updating nested option values.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Option type prefixed ID+ schema:+ type: string+ responses:+ '200':+ description: option type updated+ content:+ application/json:+ example:+ id: opt_UkLWZg9DAJ+ name: foo-size-7+ presentation: Updated Presentation+ position: 1+ filterable: true+ option_values: []+ schema:+ "$ref": "#/components/schemas/AdminOptionType"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Presentation can't be blank+ details:+ presentation:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ example: color+ presentation:+ type: string+ example: Color+ position:+ type: integer+ example: 1+ filterable:+ type: boolean+ example: true+ option_values:+ type: array+ items:+ type: object+ properties:+ id:+ type: string+ description: Existing option value ID to update+ name:+ type: string+ example: red+ presentation:+ type: string+ example: Red+ position:+ type: integer+ delete:+ summary: Delete an option type+ tags:+ - Option Types+ security:+ - api_key: []+ bearer_auth: []+ description: Deletes an option type.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Option type prefixed ID+ schema:+ type: string+ responses:+ '204':+ description: option type deleted+ "/api/v3/admin/products":+ get:+ summary: List products+ tags:+ - Products+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a paginated list of products for the current store.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Number of records per page+ schema:+ type: integer+ - name: sort+ in: query+ required: false+ description: Sort field (e.g., name, -name, price, -price, best_selling)+ schema:+ type: string+ - name: expand+ in: query+ required: false+ description: Comma-separated associations to expand (e.g., variants, variants.images)+ schema:+ type: string+ - name: q[name_cont]+ in: query+ required: false+ description: Filter by name (contains)+ schema:+ type: string+ - name: q[status_eq]+ in: query+ required: false+ description: Filter by status+ schema:+ type: string+ responses:+ '200':+ description: products found+ content:+ application/json:+ example:+ data:+ - id: prod_UkLWZg9DAJ+ name: Product 53028+ description: |-+ Veniam voluptatem possimus atque recusandae fugiat harum minima iure. Non expedita eaque animi voluptatibus quod tempore. Earum sapiente adipisci ipsam nulla doloremque aut inventore. Repudiandae aperiam maxime eaque atque sint voluptatem reiciendis suscipit. Eaque neque accusantium consequatur occaecati modi.+ Dolorem minima repellat voluptas sunt a nobis. Commodi at saepe mollitia dignissimos veritatis. Nihil minima voluptatum illo neque ratione ea reprehenderit nam. Voluptas placeat eum fugiat rerum.+ slug: product-53028+ meta_description:+ meta_keywords:+ variant_count: 0+ available_on: '2025-03-06T19:22:59.347Z'+ created_at: '2026-03-06T19:22:59.378Z'+ updated_at: '2026-03-06T19:22:59.392Z'+ 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:+ variant_id: variant_UkLWZg9DAJ+ created_at: '2026-03-06T19:22:59.381Z'+ updated_at: '2026-03-06T19:22:59.381Z'+ original_price:+ status: active+ make_active_at: '2025-03-06T19:22:59.347Z'+ discontinue_on:+ deleted_at:+ cost_price: '17.0'+ cost_currency: USD+ 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/AdminProduct"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ '401':+ description: unauthorized+ content:+ application/json:+ example:+ error:+ code: invalid_token+ message: Valid secret API key required+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ post:+ summary: Create a product+ tags:+ - Products+ security:+ - api_key: []+ bearer_auth: []+ description: |+ Creates a new product. Supports nested variants with prices and option types.++ Option types and values are auto-created if they don't exist.+ Prices are upserted by currency. Stock items are upserted by stock location.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ responses:+ '201':+ description: product created+ content:+ application/json:+ example:+ id: prod_gbHJdmfrXB+ name: New Product+ description:+ slug: new-product+ meta_description:+ meta_keywords:+ variant_count: 0+ available_on:+ created_at: '2026-03-06T19:23:00.368Z'+ updated_at: '2026-03-06T19:23:00.373Z'+ purchasable: false+ in_stock: false+ backorderable: false+ available: false+ default_variant_id: variant_gbHJdmfrXB+ thumbnail_url:+ tags: []+ price:+ id: price_gbHJdmfrXB+ 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:+ variant_id: variant_gbHJdmfrXB+ created_at: '2026-03-06T19:23:00.370Z'+ updated_at: '2026-03-06T19:23:00.370Z'+ original_price:+ status: draft+ make_active_at:+ discontinue_on:+ deleted_at:+ cost_price:+ cost_currency: USD+ schema:+ "$ref": "#/components/schemas/AdminProduct"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ example: Premium T-Shirt+ price:+ type: number+ example: 29.99+ description:+ type: string+ slug:+ type: string+ status:+ type: string+ enum:+ - draft+ - active+ - archived+ sku:+ type: string+ shipping_category_id:+ type: string+ description: Prefixed ID (e.g., sc_xxx) or integer+ tax_category_id:+ type: string+ description: Prefixed ID or integer+ taxon_ids:+ type: array+ items:+ type: string+ description: Array of prefixed taxon IDs+ tags:+ type: array+ items:+ type: string+ example:+ - eco+ - sale+ variants:+ type: array+ items:+ type: object+ properties:+ sku:+ type: string+ price:+ type: number+ option_type:+ type: string+ example: Size+ option_value:+ type: string+ example: Small+ total_on_hand:+ type: integer+ prices:+ type: array+ items:+ type: object+ properties:+ currency:+ type: string+ example: USD+ amount:+ type: number+ example: 29.99+ compare_at_amount:+ type: number+ example: 39.99+ required:+ - currency+ - amount+ required:+ - name+ - price+ - shipping_category_id+ "/api/v3/admin/products/{id}":+ get:+ summary: Get a product+ tags:+ - Products+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a single product by prefixed ID.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Product prefixed ID (e.g., prod_xxx)+ schema:+ type: string+ - name: expand+ in: query+ required: false+ description: Comma-separated associations to expand (e.g., variants)+ schema:+ type: string+ responses:+ '200':+ description: product found+ content:+ application/json:+ example:+ id: prod_UkLWZg9DAJ+ name: Product 9735+ description: |-+ Suscipit vitae ea placeat quod. Deleniti voluptas tempora in ipsum. Qui aliquam eius doloremque saepe.+ Sint eaque magnam inventore commodi architecto porro. Odit tempore sapiente maiores impedit. Asperiores commodi nisi perspiciatis eveniet. Est in reiciendis similique soluta a veniam dignissimos.+ Doloremque itaque voluptates animi corrupti modi sequi consequuntur at. Soluta recusandae nihil dolore quaerat error laboriosam eligendi. Nostrum consequuntur voluptatum distinctio at animi repellat suscipit excepturi.+ Ad amet accusantium itaque nostrum nihil corrupti impedit. Neque natus quisquam atque aspernatur placeat. Quam rerum ipsam eius eos aliquam sequi alias. Libero sapiente eligendi dolor fuga ea ab.+ Provident omnis voluptas nemo libero quod veniam nobis rem. Aperiam commodi voluptatem laborum cumque placeat quis omnis cupiditate. Saepe aliquam vitae voluptatem ullam reiciendis repellendus veritatis.+ slug: product-9735+ meta_description:+ meta_keywords:+ variant_count: 0+ available_on: '2025-03-06T19:23:00.750Z'+ created_at: '2026-03-06T19:23:00.764Z'+ updated_at: '2026-03-06T19:23:00.776Z'+ 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:+ variant_id: variant_UkLWZg9DAJ+ created_at: '2026-03-06T19:23:00.766Z'+ updated_at: '2026-03-06T19:23:00.766Z'+ original_price:+ status: active+ make_active_at: '2025-03-06T19:23:00.750Z'+ discontinue_on:+ deleted_at:+ cost_price: '17.0'+ cost_currency: USD+ schema:+ "$ref": "#/components/schemas/AdminProduct"+ '404':+ description: product not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Couldn't find Spree::Product with 'id'=245546638656678833+ [WHERE "spree_products"."deleted_at" IS NULL AND "spree_products_stores"."store_id"+ = ?]+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a product+ tags:+ - Products+ security:+ - api_key: []+ bearer_auth: []+ description: Updates a product. Only provided fields are updated.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Product prefixed ID+ schema:+ type: string+ responses:+ '200':+ description: product updated+ content:+ application/json:+ example:+ id: prod_UkLWZg9DAJ+ name: Updated Name+ description: Tenetur fugiat dolore sapiente quas nam voluptatibus+ ratione. Autem amet possimus nam magni commodi. Fuga quas suscipit+ sit placeat alias iusto iste. Autem veniam quis quasi aliquid nobis+ et sunt minus.+ slug: product-119031+ meta_description:+ meta_keywords:+ variant_count: 0+ available_on: '2025-03-06T19:23:01.409Z'+ created_at: '2026-03-06T19:23:01.422Z'+ updated_at: '2026-03-06T19:23:01.731Z'+ 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:+ variant_id: variant_UkLWZg9DAJ+ created_at: '2026-03-06T19:23:01.423Z'+ updated_at: '2026-03-06T19:23:01.423Z'+ original_price:+ status: active+ make_active_at: '2025-03-06T19:23:01.409Z'+ discontinue_on:+ deleted_at:+ cost_price: '17.0'+ cost_currency: USD+ schema:+ "$ref": "#/components/schemas/AdminProduct"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ example: Premium T-Shirt+ price:+ type: number+ example: 29.99+ description:+ type: string+ slug:+ type: string+ status:+ type: string+ enum:+ - draft+ - active+ - archived+ sku:+ type: string+ shipping_category_id:+ type: string+ description: Prefixed ID (e.g., sc_xxx) or integer+ tax_category_id:+ type: string+ description: Prefixed ID or integer+ taxon_ids:+ type: array+ items:+ type: string+ description: Array of prefixed taxon IDs+ tags:+ type: array+ items:+ type: string+ example:+ - eco+ - sale+ variants:+ type: array+ items:+ type: object+ properties:+ sku:+ type: string+ price:+ type: number+ option_type:+ type: string+ example: Size+ option_value:+ type: string+ example: Small+ total_on_hand:+ type: integer+ prices:+ type: array+ items:+ type: object+ properties:+ currency:+ type: string+ example: USD+ amount:+ type: number+ example: 29.99+ compare_at_amount:+ type: number+ example: 39.99+ required:+ - currency+ - amount+ delete:+ summary: Delete a product+ tags:+ - Products+ security:+ - api_key: []+ bearer_auth: []+ description: Soft-deletes a product.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Product prefixed ID+ schema:+ type: string+ responses:+ '204':+ description: product deleted+ "/api/v3/admin/taxonomies":+ get:+ summary: List taxonomies+ tags:+ - Taxonomies+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a paginated list of taxonomies for the current store.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Number of records per page+ schema:+ type: integer+ responses:+ '200':+ description: taxonomies found+ content:+ application/json:+ example:+ data:+ - id: txnmy_UkLWZg9DAJ+ name: Categories+ position: 1+ created_at: '2026-03-06T19:22:54.957Z'+ updated_at: '2026-03-06T19:22:54.980Z'+ root_id: txn_UkLWZg9DAJ+ - id: txnmy_gbHJdmfrXB+ name: Brands+ position: 2+ created_at: '2026-03-06T19:22:54.981Z'+ updated_at: '2026-03-06T19:22:54.989Z'+ root_id: txn_gbHJdmfrXB+ - id: txnmy_EfhxLZ9ck8+ name: Collections+ position: 3+ created_at: '2026-03-06T19:22:54.991Z'+ updated_at: '2026-03-06T19:22:55.055Z'+ root_id: txn_EfhxLZ9ck8+ - id: txnmy_VqXmZF31wY+ name: taxonomy_1+ position: 4+ created_at: '2026-03-06T19:23:02.439Z'+ updated_at: '2026-03-06T19:23:02.447Z'+ root_id: txn_OIJLhNcSbf+ meta:+ page: 1+ limit: 25+ count: 4+ pages: 1+ from: 1+ to: 4+ in: 4+ previous:+ next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/AdminTaxonomy"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ '401':+ description: unauthorized+ content:+ application/json:+ example:+ error:+ code: invalid_token+ message: Valid secret API key required+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ post:+ summary: Create a taxonomy+ tags:+ - Taxonomies+ security:+ - api_key: []+ bearer_auth: []+ description: Creates a new taxonomy.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ responses:+ '201':+ description: taxonomy created+ content:+ application/json:+ example:+ id: txnmy_uw2YK1rnl0+ name: New Taxonomy+ position: 5+ created_at: '2026-03-06T19:23:03.338Z'+ updated_at: '2026-03-06T19:23:03.348Z'+ root_id: txn_AXs1igzRC6+ schema:+ "$ref": "#/components/schemas/AdminTaxonomy"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ example: Categories+ position:+ type: integer+ example: 1+ required:+ - name+ "/api/v3/admin/taxonomies/{id}":+ get:+ summary: Get a taxonomy+ tags:+ - Taxonomies+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a single taxonomy by prefixed ID.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Taxonomy prefixed ID+ schema:+ type: string+ - name: expand+ in: query+ required: false+ description: Comma-separated associations to expand (e.g., root, taxons)+ schema:+ type: string+ responses:+ '200':+ description: taxonomy found+ content:+ application/json:+ example:+ id: txnmy_VqXmZF31wY+ name: taxonomy_5+ position: 4+ created_at: '2026-03-06T19:23:03.653Z'+ updated_at: '2026-03-06T19:23:03.664Z'+ root_id: txn_OIJLhNcSbf+ schema:+ "$ref": "#/components/schemas/AdminTaxonomy"+ '404':+ description: taxonomy not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Couldn't find Spree::Taxonomy with 'id'=245546638656678833+ [WHERE "spree_taxonomies"."store_id" = ?]+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a taxonomy+ tags:+ - Taxonomies+ security:+ - api_key: []+ bearer_auth: []+ description: Updates a taxonomy. Only provided fields are updated.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Taxonomy prefixed ID+ schema:+ type: string+ responses:+ '200':+ description: taxonomy updated+ content:+ application/json:+ example:+ id: txnmy_VqXmZF31wY+ name: Updated Taxonomy+ position: 4+ created_at: '2026-03-06T19:23:04.256Z'+ updated_at: '2026-03-06T19:23:04.555Z'+ root_id: txn_OIJLhNcSbf+ schema:+ "$ref": "#/components/schemas/AdminTaxonomy"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ example: Categories+ position:+ type: integer+ example: 1+ delete:+ summary: Delete a taxonomy+ tags:+ - Taxonomies+ security:+ - api_key: []+ bearer_auth: []+ description: Deletes a taxonomy.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Taxonomy prefixed ID+ schema:+ type: string+ responses:+ '204':+ description: taxonomy deleted+ "/api/v3/admin/taxons":+ get:+ summary: List taxons+ tags:+ - Taxons+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a flat, paginated list of all taxons for the current store.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Number of records per page+ schema:+ type: integer+ - name: q[name_cont]+ in: query+ required: false+ description: Filter by name (contains)+ 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-06T19:22:54.968Z'+ updated_at: '2026-03-06T19:22:54.978Z'+ parent_id:+ taxonomy_id: txnmy_UkLWZg9DAJ+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: true+ is_child: false+ is_leaf: true+ lft: 1+ rgt: 2+ - id: txn_gbHJdmfrXB+ name: Brands+ permalink: brands+ position: 0+ depth: 0+ meta_title:+ meta_description:+ meta_keywords:+ children_count: 0+ created_at: '2026-03-06T19:22:54.983Z'+ updated_at: '2026-03-06T19:22:54.988Z'+ parent_id:+ taxonomy_id: txnmy_gbHJdmfrXB+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: true+ is_child: false+ is_leaf: true+ lft: 3+ rgt: 4+ - id: txn_EfhxLZ9ck8+ name: Collections+ permalink: collections+ position: 0+ depth: 0+ meta_title:+ meta_description:+ meta_keywords:+ children_count: 2+ created_at: '2026-03-06T19:22:54.993Z'+ updated_at: '2026-03-06T19:22:55.054Z'+ parent_id:+ taxonomy_id: txnmy_EfhxLZ9ck8+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: true+ is_child: false+ is_leaf: false+ lft: 5+ rgt: 10+ - 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-06T19:22:55.008Z'+ updated_at: '2026-03-06T19:22:55.010Z'+ 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+ lft: 6+ rgt: 7+ - 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-06T19:22:55.020Z'+ updated_at: '2026-03-06T19:22:55.021Z'+ 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+ lft: 8+ rgt: 9+ - id: txn_OIJLhNcSbf+ name: taxonomy_10+ permalink: taxonomy-10+ position: 0+ depth: 0+ meta_title:+ meta_description:+ meta_keywords:+ children_count: 1+ created_at: '2026-03-06T19:23:05.176Z'+ updated_at: '2026-03-06T19:23:05.190Z'+ parent_id:+ taxonomy_id: txnmy_VqXmZF31wY+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: true+ is_child: false+ is_leaf: false+ lft: 11+ rgt: 14+ - id: txn_AXs1igzRC6+ name: taxon_1+ permalink: taxonomy-10/taxon-1+ position: 0+ depth: 1+ meta_title:+ meta_description:+ meta_keywords:+ children_count: 0+ created_at: '2026-03-06T19:23:05.183Z'+ updated_at: '2026-03-06T19:23:05.189Z'+ parent_id: txn_OIJLhNcSbf+ taxonomy_id: txnmy_VqXmZF31wY+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: false+ is_child: true+ is_leaf: true+ lft: 12+ rgt: 13+ meta:+ page: 1+ limit: 25+ count: 7+ pages: 1+ from: 1+ to: 7+ in: 7+ previous:+ next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/AdminTaxon"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ '401':+ description: unauthorized+ content:+ application/json:+ example:+ error:+ code: invalid_token+ message: Valid secret API key required+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/admin/taxons/{id}":+ get:+ summary: Get a taxon+ tags:+ - Taxons+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a single taxon by prefixed ID.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Taxon prefixed ID+ schema:+ type: string+ - name: expand+ in: query+ required: false+ description: Comma-separated associations to expand (e.g., parent, children,+ ancestors)+ schema:+ type: string+ responses:+ '200':+ description: taxon found+ content:+ application/json:+ example:+ id: txn_AXs1igzRC6+ name: taxon_3+ permalink: taxonomy-12/taxon-3+ position: 0+ depth: 1+ meta_title:+ meta_description:+ meta_keywords:+ children_count: 0+ created_at: '2026-03-06T19:23:05.794Z'+ updated_at: '2026-03-06T19:23:05.800Z'+ parent_id: txn_OIJLhNcSbf+ taxonomy_id: txnmy_VqXmZF31wY+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: false+ is_child: true+ is_leaf: true+ lft: 12+ rgt: 13+ schema:+ "$ref": "#/components/schemas/AdminTaxon"+ '404':+ description: taxon not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Couldn't find Spree::Taxon with 'id'=245546638656678833+ [WHERE "spree_taxonomies"."store_id" = ?]+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/admin/taxonomies/{taxonomy_id}/taxons":+ get:+ summary: List taxonomy taxons+ tags:+ - Taxons+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a paginated list of taxons belonging to a taxonomy.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: taxonomy_id+ in: path+ required: true+ description: Taxonomy prefixed ID+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Number of records per page+ schema:+ type: integer+ responses:+ '200':+ description: taxons found+ content:+ application/json:+ example:+ data:+ - id: txn_OIJLhNcSbf+ name: taxonomy_14+ permalink: taxonomy-14+ position: 0+ depth: 0+ meta_title:+ meta_description:+ meta_keywords:+ children_count: 1+ created_at: '2026-03-06T19:23:06.399Z'+ updated_at: '2026-03-06T19:23:06.415Z'+ parent_id:+ taxonomy_id: txnmy_VqXmZF31wY+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: true+ is_child: false+ is_leaf: false+ lft: 11+ rgt: 14+ - id: txn_AXs1igzRC6+ name: taxon_5+ permalink: taxonomy-14/taxon-5+ position: 0+ depth: 1+ meta_title:+ meta_description:+ meta_keywords:+ children_count: 0+ created_at: '2026-03-06T19:23:06.407Z'+ updated_at: '2026-03-06T19:23:06.414Z'+ parent_id: txn_OIJLhNcSbf+ taxonomy_id: txnmy_VqXmZF31wY+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: false+ is_child: true+ is_leaf: true+ lft: 12+ rgt: 13+ meta:+ page: 1+ limit: 25+ count: 2+ pages: 1+ from: 1+ to: 2+ in: 2+ previous:+ next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/AdminTaxon"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ post:+ summary: Create a taxon+ tags:+ - Taxons+ security:+ - api_key: []+ bearer_auth: []+ description: Creates a new taxon within a taxonomy.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: taxonomy_id+ in: path+ required: true+ description: Taxonomy prefixed ID+ schema:+ type: string+ responses:+ '201':+ description: taxon created+ content:+ application/json:+ example:+ id: txn_p6klVeMgbn+ name: New Taxon+ permalink: taxonomy-15/new-taxon+ position: 0+ depth: 1+ meta_title:+ meta_description:+ meta_keywords:+ children_count: 0+ created_at: '2026-03-06T19:23:07.002Z'+ updated_at: '2026-03-06T19:23:07.009Z'+ parent_id: txn_OIJLhNcSbf+ taxonomy_id: txnmy_VqXmZF31wY+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: false+ is_child: true+ is_leaf: true+ lft: 14+ rgt: 15+ schema:+ "$ref": "#/components/schemas/AdminTaxon"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank and Root conflict this taxonomy already+ has a root taxon+ details:+ name:+ - can't be blank+ root_conflict:+ - this taxonomy already has a root taxon+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ example: T-Shirts+ parent_id:+ type: string+ description: Parent taxon prefixed ID+ position:+ type: integer+ description:+ type: string+ permalink:+ type: string+ meta_title:+ type: string+ meta_description:+ type: string+ meta_keywords:+ type: string+ hide_from_nav:+ type: boolean+ sort_order:+ type: string+ example: manual+ required:+ - name+ "/api/v3/admin/taxonomies/{taxonomy_id}/taxons/{id}":+ get:+ summary: Get a taxonomy taxon+ tags:+ - Taxons+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a single taxon within a taxonomy.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: taxonomy_id+ in: path+ required: true+ description: Taxonomy prefixed ID+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Taxon prefixed ID+ schema:+ type: string+ - name: expand+ in: query+ required: false+ description: Comma-separated associations to expand (e.g., parent, children,+ ancestors)+ schema:+ type: string+ responses:+ '200':+ description: taxon found+ content:+ application/json:+ example:+ id: txn_AXs1igzRC6+ name: taxon_8+ permalink: taxonomy-17/taxon-8+ position: 0+ depth: 1+ meta_title:+ meta_description:+ meta_keywords:+ children_count: 0+ created_at: '2026-03-06T19:23:07.337Z'+ updated_at: '2026-03-06T19:23:07.344Z'+ parent_id: txn_OIJLhNcSbf+ taxonomy_id: txnmy_VqXmZF31wY+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: false+ is_child: true+ is_leaf: true+ lft: 12+ rgt: 13+ schema:+ "$ref": "#/components/schemas/AdminTaxon"+ '404':+ description: taxon not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Couldn't find Spree::Taxon with 'id'=245546638656678833+ [WHERE "spree_taxons"."taxonomy_id" = ?]+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a taxon+ tags:+ - Taxons+ security:+ - api_key: []+ bearer_auth: []+ description: Updates a taxon within a taxonomy. Only provided fields are updated.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: taxonomy_id+ in: path+ required: true+ description: Taxonomy prefixed ID+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Taxon prefixed ID+ schema:+ type: string+ responses:+ '200':+ description: taxon updated+ content:+ application/json:+ example:+ id: txn_AXs1igzRC6+ name: Updated Taxon+ permalink: taxonomy-19/taxon-10+ position: 0+ depth: 1+ meta_title:+ meta_description:+ meta_keywords:+ children_count: 0+ created_at: '2026-03-06T19:23:07.939Z'+ updated_at: '2026-03-06T19:23:08.228Z'+ parent_id: txn_OIJLhNcSbf+ taxonomy_id: txnmy_VqXmZF31wY+ description: ''+ description_html: ''+ image_url:+ square_image_url:+ is_root: false+ is_child: true+ is_leaf: true+ lft: 12+ rgt: 13+ schema:+ "$ref": "#/components/schemas/AdminTaxon"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ example: T-Shirts+ parent_id:+ type: string+ description: Parent taxon prefixed ID+ position:+ type: integer+ description:+ type: string+ permalink:+ type: string+ meta_title:+ type: string+ meta_description:+ type: string+ meta_keywords:+ type: string+ hide_from_nav:+ type: boolean+ sort_order:+ type: string+ example: manual+ delete:+ summary: Delete a taxon+ tags:+ - Taxons+ security:+ - api_key: []+ bearer_auth: []+ description: Deletes a taxon from a taxonomy.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: taxonomy_id+ in: path+ required: true+ description: Taxonomy prefixed ID+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Taxon prefixed ID+ schema:+ type: string+ responses:+ '204':+ description: taxon deleted+ "/api/v3/admin/products/{product_id}/variants":+ get:+ summary: List product variants+ tags:+ - Variants+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a paginated list of variants for a product, including the+ master variant.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: product_id+ in: path+ required: true+ description: Product prefixed ID+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Number of records per page+ schema:+ type: integer+ - name: expand+ in: query+ required: false+ description: Comma-separated associations to expand (e.g., images, prices,+ stock_items)+ schema:+ type: string+ responses:+ '200':+ description: variants found+ content:+ application/json:+ example:+ data:+ - id: variant_UkLWZg9DAJ+ product_id: prod_UkLWZg9DAJ+ sku: SKU-14+ is_master: true+ options_text: ''+ track_inventory: true+ image_count: 0+ created_at: '2026-03-06T19:23:08.877Z'+ updated_at: '2026-03-06T19:23:08.887Z'+ thumbnail:+ purchasable: false+ in_stock: false+ backorderable: false+ weight: 0.0+ height:+ width:+ depth:+ price:+ id:+ amount:+ amount_in_cents: 0+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$0.00"+ display_compare_at_amount:+ price_list_id:+ variant_id: variant_UkLWZg9DAJ+ created_at:+ updated_at:+ original_price:+ option_values: []+ position: 1+ tax_category_id: 1+ cost_price: '17.0'+ cost_currency: USD+ deleted_at:+ total_on_hand: 0+ - id: variant_gbHJdmfrXB+ product_id: prod_UkLWZg9DAJ+ sku: SKU-15+ is_master: false+ options_text: 'Size: S'+ track_inventory: true+ image_count: 0+ created_at: '2026-03-06T19:23:08.899Z'+ updated_at: '2026-03-06T19:23:08.913Z'+ thumbnail:+ purchasable: true+ in_stock: false+ backorderable: true+ weight: 141.64+ height: 42.69+ width: 47.17+ depth: 36.86+ price:+ id: price_gbHJdmfrXB+ 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:+ variant_id: variant_gbHJdmfrXB+ created_at: '2026-03-06T19:23:08.900Z'+ updated_at: '2026-03-06T19:23:08.900Z'+ original_price:+ option_values:+ - id: optval_UkLWZg9DAJ+ option_type_id: opt_UkLWZg9DAJ+ name: size-1+ presentation: S+ position: 1+ option_type_name: foo-size-10+ option_type_presentation: Size+ position: 2+ tax_category_id: 1+ cost_price: '17.0'+ cost_currency: USD+ deleted_at:+ total_on_hand: 0+ meta:+ page: 1+ limit: 25+ count: 2+ pages: 1+ from: 1+ to: 2+ in: 2+ previous:+ next:+ post:+ summary: Create a variant+ tags:+ - Variants+ security:+ - api_key: []+ bearer_auth: []+ description: |+ Creates a new variant for a product. Supports nested prices and stock items.++ Option types and values are auto-created if they don't exist.+ Prices are upserted by currency. Stock items are upserted by stock location.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: product_id+ in: path+ required: true+ description: Product prefixed ID+ schema:+ type: string+ responses:+ '201':+ description: variant created+ content:+ application/json:+ example:+ id: variant_EfhxLZ9ck8+ product_id: prod_UkLWZg9DAJ+ sku: NEW-SKU-001+ is_master: false+ options_text: 'Size: XL'+ track_inventory: true+ image_count: 0+ created_at: '2026-03-06T19:23:09.564Z'+ updated_at: '2026-03-06T19:23:09.566Z'+ thumbnail:+ purchasable: false+ in_stock: false+ backorderable: false+ weight: 0.0+ height:+ width:+ depth:+ price:+ id: price_EfhxLZ9ck8+ amount: '24.99'+ amount_in_cents: 2499+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$24.99"+ display_compare_at_amount:+ price_list_id:+ variant_id: variant_EfhxLZ9ck8+ created_at: '2026-03-06T19:23:09.565Z'+ updated_at: '2026-03-06T19:23:09.565Z'+ original_price:+ option_values:+ - id: optval_gbHJdmfrXB+ option_type_id: opt_gbHJdmfrXB+ name: xl+ presentation: XL+ position: 1+ option_type_name: size+ option_type_presentation: Size+ position: 3+ tax_category_id: 1+ cost_price:+ cost_currency: USD+ deleted_at:+ total_on_hand: 0+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Option value variants can't be blank+ details:+ option_value_variants:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ sku:+ type: string+ example: SKU-001+ price:+ type: number+ example: 29.99+ compare_at_price:+ type: number+ example: 39.99+ cost_price:+ type: number+ example: 10.0+ cost_currency:+ type: string+ example: USD+ weight:+ type: number+ height:+ type: number+ width:+ type: number+ depth:+ type: number+ weight_unit:+ type: string+ dimensions_unit:+ type: string+ track_inventory:+ type: boolean+ tax_category_id:+ type: string+ option_type:+ type: string+ example: Size+ description: Option type name (auto-created if needed)+ option_value:+ type: string+ example: Large+ description: Option value name (auto-created if needed)+ total_on_hand:+ type: integer+ example: 100+ position:+ type: integer+ barcode:+ type: string+ prices:+ type: array+ items:+ type: object+ properties:+ currency:+ type: string+ example: USD+ amount:+ type: number+ example: 29.99+ compare_at_amount:+ type: number+ example: 39.99+ required:+ - currency+ - amount+ stock_items:+ type: array+ items:+ type: object+ properties:+ stock_location_id:+ type: string+ count_on_hand:+ type: integer+ backorderable:+ type: boolean+ "/api/v3/admin/products/{product_id}/variants/{id}":+ get:+ summary: Get a variant+ tags:+ - Variants+ security:+ - api_key: []+ bearer_auth: []+ description: Returns a single variant by prefixed ID.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: product_id+ in: path+ required: true+ description: Product prefixed ID+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Variant prefixed ID+ schema:+ type: string+ - name: expand+ in: query+ required: false+ description: Comma-separated associations to expand (e.g., images, prices,+ stock_items)+ schema:+ type: string+ responses:+ '200':+ description: variant found+ content:+ application/json:+ example:+ id: variant_gbHJdmfrXB+ product_id: prod_UkLWZg9DAJ+ sku: SKU-21+ is_master: false+ options_text: 'Size: S'+ track_inventory: true+ image_count: 0+ created_at: '2026-03-06T19:23:09.961Z'+ updated_at: '2026-03-06T19:23:09.972Z'+ thumbnail:+ purchasable: true+ in_stock: false+ backorderable: true+ weight: 70.18+ height: 153.3+ width: 22.5+ depth: 87.39+ price:+ id: price_gbHJdmfrXB+ 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:+ variant_id: variant_gbHJdmfrXB+ created_at: '2026-03-06T19:23:09.963Z'+ updated_at: '2026-03-06T19:23:09.963Z'+ original_price:+ option_values:+ - id: optval_UkLWZg9DAJ+ option_type_id: opt_UkLWZg9DAJ+ name: size-4+ presentation: S+ position: 1+ option_type_name: foo-size-13+ option_type_presentation: Size+ position: 2+ tax_category_id: 1+ cost_price: '17.0'+ cost_currency: USD+ deleted_at:+ total_on_hand: 0+ '404':+ description: variant not found+ content:+ application/json:+ example:+ error:+ code: variant_not_found+ message: Couldn't find Spree::Variant with 'id'=245546638656678833+ [WHERE "spree_variants"."deleted_at" IS NULL AND "spree_variants"."product_id"+ = ?]+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a variant+ tags:+ - Variants+ security:+ - api_key: []+ bearer_auth: []+ description: Updates a variant. Only provided fields are updated.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: product_id+ in: path+ required: true+ description: Product prefixed ID+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Variant prefixed ID+ schema:+ type: string+ responses:+ '200':+ description: variant updated+ content:+ application/json:+ example:+ id: variant_gbHJdmfrXB+ product_id: prod_UkLWZg9DAJ+ sku: UPDATED-SKU+ is_master: false+ options_text: 'Size: S'+ track_inventory: true+ image_count: 0+ created_at: '2026-03-06T19:23:10.648Z'+ updated_at: '2026-03-06T19:23:10.946Z'+ thumbnail:+ purchasable: true+ in_stock: false+ backorderable: true+ weight: 124.1+ height: 75.25+ width: 177.81+ depth: 69.72+ price:+ id: price_gbHJdmfrXB+ 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:+ variant_id: variant_gbHJdmfrXB+ created_at: '2026-03-06T19:23:10.649Z'+ updated_at: '2026-03-06T19:23:10.649Z'+ original_price:+ option_values:+ - id: optval_UkLWZg9DAJ+ option_type_id: opt_UkLWZg9DAJ+ name: size-6+ presentation: S+ position: 1+ option_type_name: foo-size-15+ option_type_presentation: Size+ position: 2+ tax_category_id: 1+ cost_price: '17.0'+ cost_currency: USD+ deleted_at:+ total_on_hand: 0+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ sku:+ type: string+ example: SKU-001+ price:+ type: number+ example: 29.99+ compare_at_price:+ type: number+ example: 39.99+ cost_price:+ type: number+ example: 10.0+ cost_currency:+ type: string+ example: USD+ weight:+ type: number+ height:+ type: number+ width:+ type: number+ depth:+ type: number+ weight_unit:+ type: string+ dimensions_unit:+ type: string+ track_inventory:+ type: boolean+ tax_category_id:+ type: string+ option_type:+ type: string+ example: Size+ option_value:+ type: string+ example: Large+ total_on_hand:+ type: integer+ example: 100+ position:+ type: integer+ barcode:+ type: string+ prices:+ type: array+ items:+ type: object+ properties:+ currency:+ type: string+ example: USD+ amount:+ type: number+ example: 29.99+ compare_at_amount:+ type: number+ example: 39.99+ required:+ - currency+ - amount+ stock_items:+ type: array+ items:+ type: object+ properties:+ stock_location_id:+ type: string+ count_on_hand:+ type: integer+ backorderable:+ type: boolean+ delete:+ summary: Delete a variant+ tags:+ - Variants+ security:+ - api_key: []+ bearer_auth: []+ description: Soft-deletes a variant.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: product_id+ in: path+ required: true+ description: Product prefixed ID+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Variant prefixed ID+ schema:+ type: string+ responses:+ '204':+ description: variant deleted+servers:+- url: http://{defaultHost}+ variables:+ defaultHost:+ default: localhost:3000+tags:+- name: Products+ description: Product management+- name: Variants+ description: Product variant management+- name: Option Types+ description: Option type and value management+- name: Taxonomies+ description: Taxonomy management+- name: Taxons+ description: Taxon (category) management+- name: Assets+ description: Product image and asset management+- name: Prices+ description: Variant price management+x-tagGroups:+- name: Catalog+ tags:+ - Products+ - Variants+ - Assets+ - Prices+- name: Categories+ tags:+ - Taxonomies+ - Taxons+- name: Options+ tags:+ - Option Types+components:+ securitySchemes:+ api_key:+ type: apiKey+ name: x-spree-api-key+ in: header+ description: Secret API key for admin access+ bearer_auth:+ type: http+ scheme: bearer+ bearerFormat: JWT+ description: JWT token for admin user authentication+ schemas:+ PaginationMeta:+ type: object+ properties:+ page:+ type: integer+ example: 1+ limit:+ type: integer+ example: 25+ count:+ type: integer+ example: 100+ description: Total number of records+ pages:+ type: integer+ example: 4+ description: Total number of pages+ from:+ type: integer+ example: 1+ description: Index of first record on this page+ to:+ type: integer+ example: 25+ description: Index of last record on this page+ in:+ type: integer+ example: 25+ description: Number of records on this page+ previous:+ type: integer+ nullable: true+ example:+ description: Previous page number+ next:+ type: integer+ nullable: true+ example: 2+ description: Next page number+ required:+ - page+ - limit+ - count+ - pages+ - from+ - to+ - in+ ErrorResponse:+ type: object+ properties:+ error:+ type: object+ properties:+ code:+ type: string+ example: record_not_found+ message:+ type: string+ example: Record not found+ details:+ type: object+ description: Field-specific validation errors+ nullable: true+ example:+ name:+ - is too short+ - is required+ email:+ - is invalid+ required:+ - code+ - message+ required:+ - error+ example:+ error:+ code: validation_error+ message: Validation failed+ details:+ name:+ - is too short+ email:+ - is invalid+ AuthResponse:+ type: object+ properties:+ token:+ type: string+ description: JWT access token+ user:+ "$ref": "#/components/schemas/StoreCustomer"+ required:+ - token+ - user+ AdminAsset:+ type: object+ properties:+ id:+ type: string+ viewable_id:+ type: string+ type:+ type: string+ nullable: true+ viewable_type:+ type: string+ position:+ type: number+ nullable: true+ alt:+ type: string+ nullable: true+ created_at:+ type: string+ updated_at:+ type: string+ required:+ - id+ - viewable_id+ - type+ - viewable_type+ - position+ - alt+ - created_at+ - updated_at+ x-typelizer: true+ AdminCustomer:+ type: object+ properties:+ id:+ type: string+ email:+ type: string+ first_name:+ type: string+ nullable: true+ last_name:+ type: string+ nullable: true+ created_at:+ type: string+ updated_at:+ type: string+ addresses:+ type: array+ items:+ "$ref": "#/components/schemas/StoreAddress"+ default_billing_address:+ allOf:+ - "$ref": "#/components/schemas/StoreAddress"+ nullable: true+ default_shipping_address:+ allOf:+ - "$ref": "#/components/schemas/StoreAddress"+ nullable: true+ phone:+ type: string+ nullable: true+ login:+ type: string+ nullable: true+ accepts_email_marketing:+ type: boolean+ last_sign_in_at:+ type: string+ nullable: true+ current_sign_in_at:+ type: string+ nullable: true+ sign_in_count:+ type: number+ failed_attempts:+ type: number+ last_sign_in_ip:+ type: string+ nullable: true+ current_sign_in_ip:+ type: string+ nullable: true+ orders:+ type: array+ items:+ "$ref": "#/components/schemas/AdminOrder"+ required:+ - id+ - first_name+ - last_name+ - created_at+ - updated_at+ - addresses+ - default_billing_address+ - default_shipping_address+ - phone+ - login+ - accepts_email_marketing+ - last_sign_in_at+ - current_sign_in_at+ - sign_in_count+ - failed_attempts+ - last_sign_in_ip+ - current_sign_in_ip+ x-typelizer: true+ AdminImage:+ type: object+ properties:+ id:+ type: string+ viewable_id:+ type: string+ type:+ type: string+ nullable: true+ viewable_type:+ type: string+ position:+ type: number+ nullable: true+ alt:+ type: string+ nullable: true+ created_at:+ type: string+ updated_at:+ type: string+ original_url:+ type: string+ nullable: true+ mini_url:+ type: string+ nullable: true+ small_url:+ type: string+ nullable: true+ medium_url:+ type: string+ nullable: true+ large_url:+ type: string+ nullable: true+ xlarge_url:+ type: string+ nullable: true+ og_image_url:+ type: string+ nullable: true+ required:+ - id+ - viewable_id+ - type+ - viewable_type+ - position+ - alt+ - created_at+ - updated_at+ - original_url+ - mini_url+ - small_url+ - medium_url+ - large_url+ - xlarge_url+ - og_image_url+ x-typelizer: true+ AdminLineItem:+ type: object+ properties:+ id:+ type: string+ variant_id:+ type: string+ quantity:+ type: number+ currency:+ type: string+ name:+ type: string+ slug:+ type: string+ options_text:+ type: string+ price:+ type: string+ display_price:+ type: string+ total:+ type: string+ display_total:+ type: string+ adjustment_total:+ type: string+ display_adjustment_total:+ type: string+ additional_tax_total:+ type: string+ display_additional_tax_total:+ type: string+ included_tax_total:+ type: string+ display_included_tax_total:+ type: string+ promo_total:+ type: string+ display_promo_total:+ type: string+ pre_tax_amount:+ type: string+ display_pre_tax_amount:+ type: string+ discounted_amount:+ type: string+ display_discounted_amount:+ type: string+ display_compare_at_amount:+ type: string+ nullable: true+ created_at:+ type: string+ updated_at:+ type: string+ compare_at_amount:+ type: string+ nullable: true+ thumbnail_url:+ type: string+ nullable: true+ option_values:+ type: array+ items:+ "$ref": "#/components/schemas/StoreOptionValue"+ digital_links:+ type: array+ items:+ "$ref": "#/components/schemas/StoreDigitalLink"+ metadata:+ type: object+ nullable: true+ required:+ - id+ - variant_id+ - quantity+ - currency+ - name+ - slug+ - options_text+ - price+ - display_price+ - total+ - display_total+ - adjustment_total+ - display_adjustment_total+ - additional_tax_total+ - display_additional_tax_total+ - included_tax_total+ - display_included_tax_total+ - promo_total+ - display_promo_total+ - pre_tax_amount+ - display_pre_tax_amount+ - discounted_amount+ - display_discounted_amount+ - display_compare_at_amount+ - created_at+ - updated_at+ - compare_at_amount+ - thumbnail_url+ - option_values+ - digital_links+ - metadata+ x-typelizer: true+ AdminMetafield:+ type: object+ properties:+ id:+ type: string+ name:+ type: string+ type:+ type: string+ key:+ type: string+ value:+ type: object+ display_on:+ type: string+ required:+ - id+ - name+ - type+ - key+ - value+ - display_on+ x-typelizer: true+ AdminOptionType:+ type: object+ properties:+ id:+ type: string+ name:+ type: string+ presentation:+ type: string+ position:+ type: number+ filterable:+ type: boolean+ option_values:+ type: array+ items:+ "$ref": "#/components/schemas/AdminOptionValue"+ required:+ - id+ - name+ - presentation+ - position+ - filterable+ - option_values+ x-typelizer: true+ AdminOptionValue:+ type: object+ properties:+ id:+ type: string+ option_type_id:+ type: string+ name:+ type: string+ presentation:+ type: string+ position:+ type: number+ option_type_name:+ type: string+ option_type_presentation:+ type: string+ required:+ - id+ - option_type_id+ - name+ - presentation+ - position+ - option_type_name+ - option_type_presentation+ x-typelizer: true+ AdminOrder:+ type: object+ properties:+ id:+ type: string+ number:+ type: string+ state:+ type: string+ checkout_steps:+ type: array+ items:+ type: string+ token:+ type: string+ email:+ type: string+ nullable: true+ special_instructions:+ type: string+ nullable: true+ currency:+ type: string+ locale:+ type: string+ nullable: true+ item_count:+ type: number+ state_lock_version:+ type: number+ shipment_state:+ type: string+ nullable: true+ payment_state:+ type: string+ nullable: true+ item_total:+ type: string+ display_item_total:+ type: string+ ship_total:+ type: string+ display_ship_total:+ type: string+ adjustment_total:+ type: string+ display_adjustment_total:+ type: string+ promo_total:+ type: string+ display_promo_total:+ type: string+ tax_total:+ type: string+ display_tax_total:+ type: string+ included_tax_total:+ type: string+ display_included_tax_total:+ type: string+ additional_tax_total:+ type: string+ display_additional_tax_total:+ type: string+ total:+ type: string+ display_total:+ type: string+ completed_at:+ type: string+ nullable: true+ created_at:+ type: string+ updated_at:+ type: string+ order_promotions:+ type: array+ items:+ "$ref": "#/components/schemas/StoreOrderPromotion"+ line_items:+ type: array+ items:+ "$ref": "#/components/schemas/AdminLineItem"+ shipments:+ type: array+ items:+ "$ref": "#/components/schemas/StoreShipment"+ payments:+ type: array+ items:+ "$ref": "#/components/schemas/StorePayment"+ bill_address:+ allOf:+ - "$ref": "#/components/schemas/StoreAddress"+ nullable: true+ ship_address:+ allOf:+ - "$ref": "#/components/schemas/StoreAddress"+ nullable: true+ payment_methods:+ type: array+ items:+ "$ref": "#/components/schemas/StorePaymentMethod"+ channel:+ type: string+ nullable: true+ last_ip_address:+ type: string+ nullable: true+ considered_risky:+ type: boolean+ confirmation_delivered:+ type: boolean+ store_owner_notification_delivered:+ type: boolean+ internal_note:+ type: string+ nullable: true+ approver_id:+ type: string+ nullable: true+ canceled_at:+ type: string+ nullable: true+ approved_at:+ type: string+ nullable: true+ metadata:+ type: object+ nullable: true+ canceler_id:+ type: string+ nullable: true+ created_by_id:+ type: string+ nullable: true+ user:+ "$ref": "#/components/schemas/AdminCustomer"+ required:+ - id+ - number+ - state+ - checkout_steps+ - token+ - special_instructions+ - currency+ - locale+ - item_count+ - state_lock_version+ - shipment_state+ - payment_state+ - item_total+ - display_item_total+ - ship_total+ - display_ship_total+ - adjustment_total+ - display_adjustment_total+ - promo_total+ - display_promo_total+ - tax_total+ - display_tax_total+ - included_tax_total+ - display_included_tax_total+ - additional_tax_total+ - display_additional_tax_total+ - total+ - display_total+ - completed_at+ - created_at+ - updated_at+ - order_promotions+ - line_items+ - shipments+ - payments+ - bill_address+ - ship_address+ - payment_methods+ - channel+ - last_ip_address+ - considered_risky+ - confirmation_delivered+ - store_owner_notification_delivered+ - internal_note+ - approver_id+ - canceled_at+ - approved_at+ - metadata+ - canceler_id+ - created_by_id+ x-typelizer: true+ AdminPrice:+ type: object+ properties:+ id:+ type: string+ amount:+ type: string+ nullable: true+ amount_in_cents:+ type: number+ nullable: true+ compare_at_amount:+ type: string+ nullable: true+ compare_at_amount_in_cents:+ type: number+ nullable: true+ currency:+ type: string+ nullable: true+ display_amount:+ type: string+ nullable: true+ display_compare_at_amount:+ type: string+ nullable: true+ price_list_id:+ type: string+ nullable: true+ variant_id:+ type: string+ nullable: true+ created_at:+ type: string+ updated_at:+ type: string+ required:+ - id+ - amount+ - amount_in_cents+ - compare_at_amount+ - compare_at_amount_in_cents+ - currency+ - display_amount+ - display_compare_at_amount+ - price_list_id+ - variant_id+ - created_at+ - updated_at+ x-typelizer: true+ AdminProduct:+ type: object+ properties:+ id:+ type: string+ name:+ type: string+ description:+ type: string+ nullable: true+ slug:+ type: string+ meta_description:+ type: string+ nullable: true+ meta_keywords:+ type: string+ nullable: true+ variant_count:+ type: number+ available_on:+ type: string+ nullable: true+ created_at:+ type: string+ updated_at:+ type: string+ purchasable:+ type: boolean+ in_stock:+ type: boolean+ backorderable:+ type: boolean+ available:+ type: boolean+ default_variant_id:+ type: string+ thumbnail_url:+ type: string+ nullable: true+ tags:+ type: array+ items:+ type: string+ price:+ "$ref": "#/components/schemas/AdminPrice"+ original_price:+ allOf:+ - "$ref": "#/components/schemas/AdminPrice"+ nullable: true+ images:+ type: array+ items:+ "$ref": "#/components/schemas/AdminImage"+ variants:+ type: array+ items:+ "$ref": "#/components/schemas/AdminVariant"+ default_variant:+ "$ref": "#/components/schemas/AdminVariant"+ master_variant:+ "$ref": "#/components/schemas/AdminVariant"+ option_types:+ type: array+ items:+ "$ref": "#/components/schemas/AdminOptionType"+ taxons:+ type: array+ items:+ "$ref": "#/components/schemas/AdminTaxon"+ metafields:+ type: array+ items:+ "$ref": "#/components/schemas/AdminMetafield"+ status:+ type: string+ make_active_at:+ type: string+ nullable: true+ discontinue_on:+ type: string+ nullable: true+ deleted_at:+ type: string+ nullable: true+ cost_price:+ type: string+ nullable: true+ cost_currency:+ type: string+ nullable: true+ required:+ - id+ - name+ - description+ - slug+ - meta_description+ - meta_keywords+ - variant_count+ - available_on+ - created_at+ - updated_at+ - purchasable+ - in_stock+ - backorderable+ - available+ - default_variant_id+ - thumbnail_url+ - tags+ - price+ - original_price+ - status+ - make_active_at+ - discontinue_on+ - deleted_at+ - cost_price+ - cost_currency+ x-typelizer: true+ AdminStockItem:+ type: object+ properties:+ id:+ type: string+ count_on_hand:+ type: number+ backorderable:+ type: boolean+ created_at:+ type: string+ updated_at:+ type: string+ stock_location_id:+ type: string+ nullable: true+ variant_id:+ type: string+ nullable: true+ required:+ - id+ - count_on_hand+ - backorderable+ - created_at+ - updated_at+ - stock_location_id+ - variant_id+ x-typelizer: true+ AdminTaxon:+ 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/AdminTaxon"+ children:+ type: array+ items:+ "$ref": "#/components/schemas/AdminTaxon"+ ancestors:+ type: array+ items:+ "$ref": "#/components/schemas/AdminTaxon"+ metafields:+ type: array+ items:+ "$ref": "#/components/schemas/AdminMetafield"+ lft:+ type: number+ rgt:+ type: number+ 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+ - lft+ - rgt+ x-typelizer: true+ AdminTaxonomy:+ 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/AdminTaxon"+ taxons:+ type: array+ items:+ "$ref": "#/components/schemas/AdminTaxon"+ metafields:+ type: array+ items:+ "$ref": "#/components/schemas/AdminMetafield"+ required:+ - id+ - name+ - position+ - created_at+ - updated_at+ - root_id+ x-typelizer: true+ AdminVariant:+ type: object+ properties:+ id:+ type: string+ product_id:+ type: string+ sku:+ type: string+ nullable: true+ is_master:+ type: boolean+ options_text:+ type: string+ track_inventory:+ type: boolean+ image_count:+ type: number+ created_at:+ type: string+ updated_at:+ type: string+ thumbnail:+ type: string+ nullable: true+ purchasable:+ type: boolean+ in_stock:+ type: boolean+ backorderable:+ type: boolean+ weight:+ type: number+ nullable: true+ height:+ type: number+ nullable: true+ width:+ type: number+ nullable: true+ depth:+ type: number+ nullable: true+ price:+ "$ref": "#/components/schemas/AdminPrice"+ original_price:+ allOf:+ - "$ref": "#/components/schemas/AdminPrice"+ nullable: true+ images:+ type: array+ items:+ "$ref": "#/components/schemas/AdminImage"+ option_values:+ type: array+ items:+ "$ref": "#/components/schemas/AdminOptionValue"+ metafields:+ type: array+ items:+ "$ref": "#/components/schemas/AdminMetafield"+ position:+ type: number+ tax_category_id:+ type: string+ nullable: true+ cost_price:+ type: string+ nullable: true+ cost_currency:+ type: string+ nullable: true+ deleted_at:+ type: string+ nullable: true+ total_on_hand:+ type: number+ nullable: true+ prices:+ type: array+ items:+ "$ref": "#/components/schemas/AdminPrice"+ stock_items:+ type: array+ items:+ "$ref": "#/components/schemas/AdminStockItem"+ required:+ - id+ - product_id+ - sku+ - is_master+ - options_text+ - track_inventory+ - image_count+ - created_at+ - updated_at+ - thumbnail+ - purchasable+ - in_stock+ - backorderable+ - weight+ - height+ - width+ - depth+ - price+ - original_price+ - option_values+ - position+ - tax_category_id+ - cost_price+ - cost_currency+ - deleted_at+ - total_on_hand+ x-typelizer: truediff --git a/packages/sdk/package-lock.json b/packages/sdk/package-lock.jsonindex 9f8bb22b4c..c13167a8ef 100644--- a/packages/sdk/package-lock.json+++ b/packages/sdk/package-lock.json@@ -1,12 +1,12 @@{"name": "@spree/sdk",- "version": "0.5.0",+ "version": "0.6.9","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "@spree/sdk",- "version": "0.5.0",+ "version": "0.6.9","license": "MIT","devDependencies": {"@changesets/changelog-github": "^0.5.2",@@ -18,6 +18,7 @@"tsx": "^4.0.0","typescript": "^5.3.0","vitest": "^4.0.18",+ "yaml": "^2.8.2","zod": "^4.3.6"},"engines": {@@ -4073,6 +4074,22 @@"node": ">=10"}},+ "node_modules/yaml": {+ "version": "2.8.2",+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz",+ "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==",+ "dev": true,+ "license": "ISC",+ "bin": {+ "yaml": "bin.mjs"+ },+ "engines": {+ "node": ">= 14.6"+ },+ "funding": {+ "url": "https://github.com/sponsors/eemeli"+ }+ },"node_modules/yargs": {"version": "17.7.2","resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz",diff --git a/packages/sdk/package.json b/packages/sdk/package.jsonindex 4ab8ecc3e7..2dc0000386 100644--- a/packages/sdk/package.json+++ b/packages/sdk/package.json@@ -54,6 +54,7 @@],"scripts": {"generate:zod": "tsx scripts/generate-zod.ts",+ "generate:admin-client": "tsx scripts/generate-admin-client.ts","build": "tsup","dev": "tsup --watch","console": "tsx console.ts",@@ -91,14 +92,14 @@"devDependencies": {"@changesets/changelog-github": "^0.6.0","@changesets/cli": "^2.30.0",- "@spree/sdk-core": "workspace:*",- "@types/node": "^25.5.2",- "@vitest/coverage-v8": "^4.1.4",- "msw": "^2.13.2",- "tsup": "^8.5.1",- "tsx": "^4.21.0",- "typescript": "^6.0.2",- "vitest": "^4.1.4",+ "@types/node": "^25.5.0",+ "@vitest/coverage-v8": "^4.1.2",+ "msw": "^2.12.14",+ "tsup": "^8.0.0",+ "tsx": "^4.0.0",+ "typescript": "^5.3.0",+ "vitest": "^4.0.18",+ "yaml": "^2.8.2","zod": "^4.3.6"},"peerDependencies": {diff --git a/packages/sdk/scripts/generate-admin-client.ts b/packages/sdk/scripts/generate-admin-client.tsnew file mode 100644index 0000000000..7d5469c368--- /dev/null+++ b/packages/sdk/scripts/generate-admin-client.ts@@ -0,0 +1,767 @@+/**+ * Generates admin-client.ts from the Admin API OpenAPI spec (admin.yaml).+ *+ * Usage: tsx scripts/generate-admin-client.ts+ *+ * Reads: docs/api-reference/admin.yaml+ * Writes: src/admin-client.ts+ *+ * The generated client follows the same patterns as the hand-written store-client.ts:+ * - Namespace-based: client.admin.products.list(), client.admin.products.get(id)+ * - Uses RequestFn, PaginatedResponse<T>, RequestOptions from request.ts+ * - Uses Typelizer-generated Admin* types for response typing+ * - Generates request param interfaces for create/update bodies+ */++import * as fs from 'node:fs';+import * as path from 'node:path';++// ---------------------------------------------------------------------------+// YAML Parser (minimal, no dependency)+// ---------------------------------------------------------------------------++/** Dead-simple YAML-to-JSON for the subset rswag produces. */+function parseYaml(text: string): unknown {+ // Use JSON via js-yaml if available, otherwise fall back to line-by-line+ // Since we don't want extra deps, we shell out to node's built-in YAML support+ // Actually, Node 18+ doesn't have built-in YAML. Let's do a minimal parser.+ // The rswag output is simple enough: no anchors, no multi-doc, no flow style.++ const lines = text.split('\n');+ const root: Record<string, unknown> = {};+ const stack: { indent: number; obj: Record<string, unknown> | unknown[] }[] = [+ { indent: -1, obj: root },+ ];++ function currentContainer() {+ return stack[stack.length - 1];+ }++ function setValue(container: Record<string, unknown> | unknown[], key: string | null, value: unknown) {+ if (Array.isArray(container)) {+ container.push(value);+ } else if (key) {+ container[key] = value;+ }+ }++ for (let i = 0; i < lines.length; i++) {+ const raw = lines[i];+ if (raw.trimStart().startsWith('#') || raw.trim() === '' || raw.trim() === '---') continue;++ const indent = raw.search(/\S/);+ const trimmed = raw.trim();++ // Pop stack to find parent+ while (stack.length > 1 && indent <= currentContainer().indent) {+ stack.pop();+ }++ const isArrayItem = trimmed.startsWith('- ');+ const content = isArrayItem ? trimmed.slice(2).trim() : trimmed;++ if (isArrayItem) {+ // Ensure parent value is an array+ const parent = currentContainer();+ // The parent's current value should be an array+ // If the content is "key: value", it's an object in the array+ if (content.includes(': ')) {+ const obj: Record<string, unknown> = {};+ const [k, ...rest] = content.split(': ');+ const v = rest.join(': ').trim();+ obj[k.trim()] = parseScalar(v);+ if (Array.isArray(parent.obj)) {+ parent.obj.push(obj);+ }+ stack.push({ indent: indent + 2, obj });+ } else {+ if (Array.isArray(parent.obj)) {+ parent.obj.push(parseScalar(content));+ }+ }+ continue;+ }++ // key: value or key:+ const colonIdx = content.indexOf(':');+ if (colonIdx === -1) continue;++ const key = content.slice(0, colonIdx).trim();+ const rawValue = content.slice(colonIdx + 1).trim();++ if (rawValue === '' || rawValue === '|' || rawValue === '>') {+ // Nested object or block scalar+ if (rawValue === '|' || rawValue === '>') {+ // Block scalar — collect indented lines+ const blockLines: string[] = [];+ const blockIndent = indent + 2;+ while (i + 1 < lines.length) {+ const nextLine = lines[i + 1];+ const nextIndent = nextLine.search(/\S/);+ if (nextIndent >= blockIndent || nextLine.trim() === '') {+ blockLines.push(nextLine.slice(blockIndent));+ i++;+ } else {+ break;+ }+ }+ const text = blockLines.join(rawValue === '|' ? '\n' : ' ').trim();+ setValue(currentContainer().obj, key, text);+ } else {+ // Check if next line starts with '- ' (array)+ const nextLine = lines[i + 1]?.trim();+ const child: Record<string, unknown> | unknown[] = nextLine?.startsWith('- ') ? [] : {};+ setValue(currentContainer().obj, key, child);+ stack.push({ indent, obj: child });+ }+ } else {+ setValue(currentContainer().obj, key, parseScalar(rawValue));+ }+ }++ return root;+}++function parseScalar(s: string): unknown {+ if (s === 'true') return true;+ if (s === 'false') return false;+ if (s === 'null') return null;+ if (/^-?\d+$/.test(s)) return parseInt(s, 10);+ if (/^-?\d+\.\d+$/.test(s)) return parseFloat(s);+ // Strip quotes+ if ((s.startsWith("'") && s.endsWith("'")) || (s.startsWith('"') && s.endsWith('"'))) {+ return s.slice(1, -1);+ }+ return s;+}++// ---------------------------------------------------------------------------+// OpenAPI types (just what we need)+// ---------------------------------------------------------------------------++interface OpenApiSpec {+ paths: Record<string, Record<string, OpenApiOperation>>;+ components?: { schemas?: Record<string, unknown> };+ tags?: Array<{ name: string; description?: string }>;+}++interface OpenApiOperation {+ summary?: string;+ description?: string;+ tags?: string[];+ parameters?: OpenApiParameter[];+ requestBody?: {+ content?: Record<string, { schema?: OpenApiSchema }>;+ };+ responses?: Record<string, { description?: string; content?: Record<string, { schema?: OpenApiSchema }> }>;+}++interface OpenApiParameter {+ name: string;+ in: string;+ required?: boolean;+ description?: string;+ schema?: OpenApiSchema;+}++interface OpenApiSchema {+ type?: string;+ properties?: Record<string, OpenApiSchema>;+ items?: OpenApiSchema;+ required?: string[];+ $ref?: string;+ enum?: unknown[];+ nullable?: boolean;+ description?: string;+ example?: unknown;+}++// ---------------------------------------------------------------------------+// Path analysis+// ---------------------------------------------------------------------------++interface ResourceEndpoint {+ method: string; // GET, POST, PATCH, DELETE+ path: string;+ operation: OpenApiOperation;+ action: 'list' | 'get' | 'create' | 'update' | 'delete' | 'custom';+ customAction?: string;+}++interface Resource {+ /** e.g. 'products', 'option_types' */+ name: string;+ /** e.g. 'Products' — from tag */+ tag: string;+ /** The base path for this resource, e.g. '/api/v3/admin/products' */+ basePath: string;+ /** Parent resource name if nested, e.g. 'products' for variants */+ parentName?: string;+ /** Parent path param, e.g. 'product_id' */+ parentParam?: string;+ endpoints: ResourceEndpoint[];+}++const API_PREFIX = '/api/v3/admin';++function classifyAction(method: string, path: string, basePath: string): { action: ResourceEndpoint['action']; customAction?: string } {+ const relative = path.slice(basePath.length);++ if (method === 'GET' && (relative === '' || relative === '/')) return { action: 'list' };+ if (method === 'GET' && relative === '/{id}') return { action: 'get' };+ if (method === 'POST' && (relative === '' || relative === '/')) return { action: 'create' };+ if (method === 'PATCH' && relative === '/{id}') return { action: 'update' };+ if (method === 'PUT' && relative === '/{id}') return { action: 'update' };+ if (method === 'DELETE' && relative === '/{id}') return { action: 'delete' };++ // Custom actions like POST /products/{id}/clone+ const customMatch = relative.match(/^\/{id}\/(\w+)$/);+ if (customMatch) return { action: 'custom', customAction: customMatch[1] };++ // Member-less custom: POST /products/import+ const rootCustom = relative.match(/^\/(\w+)$/);+ if (rootCustom) return { action: 'custom', customAction: rootCustom[1] };++ return { action: 'custom', customAction: relative.replace(/[{}\/]/g, '_').replace(/^_+|_+$/g, '') };+}++function analyzeResources(spec: OpenApiSpec): Resource[] {+ const resourceMap = new Map<string, Resource>();++ for (const [fullPath, methods] of Object.entries(spec.paths)) {+ if (!fullPath.startsWith(API_PREFIX)) continue;++ const apiPath = fullPath.slice(API_PREFIX.length); // e.g. '/products', '/products/{id}'++ for (const [method, operation] of Object.entries(methods)) {+ if (!operation || typeof operation !== 'object') continue;+ const httpMethod = method.toUpperCase();+ if (!['GET', 'POST', 'PATCH', 'PUT', 'DELETE'].includes(httpMethod)) continue;++ const tag = operation.tags?.[0] || 'Unknown';++ // Determine resource name and nesting+ // /products → resource=products+ // /products/{id} → resource=products+ // /products/{product_id}/variants → resource=variants, parent=products+ // /products/{product_id}/variants/{id} → resource=variants, parent=products+ const segments = apiPath.split('/').filter(Boolean);++ let resourceName: string;+ let basePath: string;+ let parentName: string | undefined;+ let parentParam: string | undefined;++ if (segments.length >= 3 && segments[1].startsWith('{') && segments[1].endsWith('}')) {+ // Nested: /products/{product_id}/variants...+ parentName = segments[0];+ parentParam = segments[1].slice(1, -1); // remove { }+ resourceName = segments[2];+ basePath = `${API_PREFIX}/${segments[0]}/${segments[1]}/${segments[2]}`;+ } else {+ resourceName = segments[0];+ basePath = `${API_PREFIX}/${segments[0]}`;+ }++ const resourceKey = parentName ? `${parentName}.${resourceName}` : resourceName;+ const { action, customAction } = classifyAction(httpMethod, fullPath, basePath);++ if (!resourceMap.has(resourceKey)) {+ resourceMap.set(resourceKey, {+ name: resourceName,+ tag,+ basePath,+ parentName,+ parentParam,+ endpoints: [],+ });+ }++ resourceMap.get(resourceKey)!.endpoints.push({+ method: httpMethod,+ path: fullPath,+ operation,+ action,+ customAction,+ });+ }+ }++ return Array.from(resourceMap.values());+}++// ---------------------------------------------------------------------------+// Type name helpers+// ---------------------------------------------------------------------------++/** 'products' → 'Product', 'option_types' → 'OptionType' */+function singularPascal(name: string): string {+ // Handle snake_case+ const pascal = name+ .split('_')+ .map((s) => s.charAt(0).toUpperCase() + s.slice(1))+ .join('');++ // Simple singularization+ if (pascal.endsWith('ies')) return pascal.slice(0, -3) + 'y';+ if (pascal.endsWith('ses')) return pascal.slice(0, -2);+ if (pascal.endsWith('s')) return pascal.slice(0, -1);+ return pascal;+}++/** 'option_types' → 'optionTypes' */+function camelCase(name: string): string {+ return name.replace(/_(\w)/g, (_, c) => c.toUpperCase());+}++function getResponseType(resource: Resource): string {+ return `Admin${singularPascal(resource.name)}`;+}++// ---------------------------------------------------------------------------+// Request body type generation+// ---------------------------------------------------------------------------++function schemaToTsType(schema: OpenApiSchema, indent = 2): string {+ if (schema.$ref) {+ const refName = schema.$ref.split('/').pop()!;+ return refName;+ }++ if (schema.type === 'string') {+ if (schema.enum) return schema.enum.map((e) => `'${e}'`).join(' | ');+ return 'string';+ }+ if (schema.type === 'number' || schema.type === 'integer') return 'number';+ if (schema.type === 'boolean') return 'boolean';++ if (schema.type === 'array' && schema.items) {+ const itemType = schemaToTsType(schema.items, indent);+ return `Array<${itemType}>`;+ }++ if (schema.type === 'object' && schema.properties) {+ const required = new Set(schema.required || []);+ const pad = ' '.repeat(indent);+ const lines = Object.entries(schema.properties).map(([key, prop]) => {+ const opt = required.has(key) ? '' : '?';+ const type = schemaToTsType(prop as OpenApiSchema, indent + 2);+ return `${pad}${key}${opt}: ${type};`;+ });+ return `{\n${lines.join('\n')}\n${' '.repeat(indent - 2)}}`;+ }++ return 'unknown';+}++function generateRequestParamType(+ resource: Resource,+ action: 'create' | 'update',+ operation: OpenApiOperation+): { typeName: string; typeBody: string } | null {+ // Find request body schema+ const bodyParam = operation.parameters?.find((p) => p.name === 'body' && p.in === 'body');+ const bodySchema = (bodyParam as unknown as { schema?: OpenApiSchema })?.schema;++ // Also check requestBody (OpenAPI 3.0 style)+ const requestBodySchema =+ operation.requestBody?.content?.['application/json']?.schema;++ const schema = bodySchema || requestBodySchema;+ if (!schema?.properties) return null;++ const typeName = `Admin${singularPascal(resource.name)}${action === 'create' ? 'Create' : 'Update'}Params`;+ const typeBody = schemaToTsType(schema);++ return { typeName, typeBody };+}++// ---------------------------------------------------------------------------+// Code generation+// ---------------------------------------------------------------------------++function generateResourceMethods(resource: Resource, paramTypes: Map<string, string>): string {+ const lines: string[] = [];+ const responseType = getResponseType(resource);+ const hasParent = !!resource.parentName;+ const parentParamName = resource.parentParam ? camelCase(resource.parentParam) : '';++ for (const endpoint of resource.endpoints) {+ const { action, method, operation, customAction } = endpoint;++ const summary = operation.summary || '';+ const jsdoc = summary ? ` /** ${summary} */` : '';++ switch (action) {+ case 'list': {+ if (jsdoc) lines.push(jsdoc);+ if (hasParent) {+ lines.push(` list: (`);+ lines.push(` ${parentParamName}: string,`);+ lines.push(` params?: ListParams,`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<PaginatedResponse<${responseType}>> =>`);+ lines.push(` this.request<PaginatedResponse<${responseType}>>('GET', \`/${resource.parentName}/\${${parentParamName}}/${resource.name}\`, {`);+ lines.push(` ...options,`);+ lines.push(` params: transformListParams({ ...params }),`);+ lines.push(` }),`);+ } else {+ lines.push(` list: (`);+ lines.push(` params?: ListParams,`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<PaginatedResponse<${responseType}>> =>`);+ lines.push(` this.request<PaginatedResponse<${responseType}>>('GET', '/${resource.name}', {`);+ lines.push(` ...options,`);+ lines.push(` params: transformListParams({ ...params }),`);+ lines.push(` }),`);+ }+ break;+ }++ case 'get': {+ if (jsdoc) lines.push(jsdoc);+ if (hasParent) {+ lines.push(` get: (`);+ lines.push(` ${parentParamName}: string,`);+ lines.push(` id: string,`);+ lines.push(` params?: { expand?: string[] },`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<${responseType}> =>`);+ lines.push(` this.request<${responseType}>('GET', \`/${resource.parentName}/\${${parentParamName}}/${resource.name}/\${id}\`, {`);+ lines.push(` ...options,`);+ lines.push(` params: getParams(params),`);+ lines.push(` }),`);+ } else {+ lines.push(` get: (`);+ lines.push(` id: string,`);+ lines.push(` params?: { expand?: string[] },`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<${responseType}> =>`);+ lines.push(` this.request<${responseType}>('GET', \`/${resource.name}/\${id}\`, {`);+ lines.push(` ...options,`);+ lines.push(` params: getParams(params),`);+ lines.push(` }),`);+ }+ break;+ }++ case 'create': {+ const createTypeName = `Admin${singularPascal(resource.name)}CreateParams`;+ const paramType = paramTypes.has(createTypeName) ? createTypeName : 'Record<string, unknown>';+ if (jsdoc) lines.push(jsdoc);+ if (hasParent) {+ lines.push(` create: (`);+ lines.push(` ${parentParamName}: string,`);+ lines.push(` params: ${paramType},`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<${responseType}> =>`);+ lines.push(` this.request<${responseType}>('POST', \`/${resource.parentName}/\${${parentParamName}}/${resource.name}\`, {`);+ lines.push(` ...options,`);+ lines.push(` body: params,`);+ lines.push(` }),`);+ } else {+ lines.push(` create: (`);+ lines.push(` params: ${paramType},`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<${responseType}> =>`);+ lines.push(` this.request<${responseType}>('POST', '/${resource.name}', {`);+ lines.push(` ...options,`);+ lines.push(` body: params,`);+ lines.push(` }),`);+ }+ break;+ }++ case 'update': {+ const updateTypeName = `Admin${singularPascal(resource.name)}UpdateParams`;+ const paramType = paramTypes.has(updateTypeName) ? updateTypeName : 'Record<string, unknown>';+ if (jsdoc) lines.push(jsdoc);+ if (hasParent) {+ lines.push(` update: (`);+ lines.push(` ${parentParamName}: string,`);+ lines.push(` id: string,`);+ lines.push(` params: ${paramType},`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<${responseType}> =>`);+ lines.push(` this.request<${responseType}>('PATCH', \`/${resource.parentName}/\${${parentParamName}}/${resource.name}/\${id}\`, {`);+ lines.push(` ...options,`);+ lines.push(` body: params,`);+ lines.push(` }),`);+ } else {+ lines.push(` update: (`);+ lines.push(` id: string,`);+ lines.push(` params: ${paramType},`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<${responseType}> =>`);+ lines.push(` this.request<${responseType}>('PATCH', \`/${resource.name}/\${id}\`, {`);+ lines.push(` ...options,`);+ lines.push(` body: params,`);+ lines.push(` }),`);+ }+ break;+ }++ case 'delete': {+ if (jsdoc) lines.push(jsdoc);+ if (hasParent) {+ lines.push(` delete: (`);+ lines.push(` ${parentParamName}: string,`);+ lines.push(` id: string,`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<void> =>`);+ lines.push(` this.request<void>('DELETE', \`/${resource.parentName}/\${${parentParamName}}/${resource.name}/\${id}\`, options),`);+ } else {+ lines.push(` delete: (`);+ lines.push(` id: string,`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<void> =>`);+ lines.push(` this.request<void>('DELETE', \`/${resource.name}/\${id}\`, options),`);+ }+ break;+ }++ case 'custom': {+ if (!customAction) break;+ const fnName = camelCase(customAction);+ if (jsdoc) lines.push(jsdoc);+ // Custom actions are always on a member (POST /resources/{id}/action)+ if (method === 'POST' || method === 'PATCH') {+ if (hasParent) {+ lines.push(` ${fnName}: (`);+ lines.push(` ${parentParamName}: string,`);+ lines.push(` id: string,`);+ lines.push(` params?: Record<string, unknown>,`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<${responseType}> =>`);+ lines.push(` this.request<${responseType}>('${method}', \`/${resource.parentName}/\${${parentParamName}}/${resource.name}/\${id}/${customAction}\`, {`);+ lines.push(` ...options,`);+ lines.push(` body: params,`);+ lines.push(` }),`);+ } else {+ lines.push(` ${fnName}: (`);+ lines.push(` id: string,`);+ lines.push(` params?: Record<string, unknown>,`);+ lines.push(` options?: RequestOptions`);+ lines.push(` ): Promise<${responseType}> =>`);+ lines.push(` this.request<${responseType}>('${method}', \`/${resource.name}/\${id}/${customAction}\`, {`);+ lines.push(` ...options,`);+ lines.push(` body: params,`);+ lines.push(` }),`);+ }+ }+ break;+ }+ }++ lines.push('');+ }++ return lines.join('\n');+}++function generateParamsFile(paramTypes: Map<string, string>): string {+ const out: string[] = [];++ out.push(`// This file is auto-generated by scripts/generate-admin-client.ts`);+ out.push(`// Do not edit manually. Run: npm run generate:admin-client`);+ out.push(``);+ out.push(`// Request parameter types (generated from OpenAPI request bodies)`);+ out.push(``);++ for (const [name, body] of paramTypes) {+ out.push(`export interface ${name} ${body}`);+ out.push(``);+ }++ return out.join('\n');+}++function generateClient(spec: OpenApiSpec): { client: string; params: string } {+ const resources = analyzeResources(spec);++ // Collect all param types from request bodies+ const paramTypes = new Map<string, string>();+ for (const resource of resources) {+ for (const endpoint of resource.endpoints) {+ if (endpoint.action === 'create' || endpoint.action === 'update') {+ const result = generateRequestParamType(resource, endpoint.action, endpoint.operation);+ if (result) {+ paramTypes.set(result.typeName, result.typeBody);+ }+ }+ }+ }++ // Collect all response types used+ const responseTypes = new Set<string>();+ for (const resource of resources) {+ responseTypes.add(getResponseType(resource));+ }++ // Group resources: top-level vs nested+ const topLevel = resources.filter((r) => !r.parentName);+ const nested = resources.filter((r) => r.parentName);++ // Build imports+ const importedTypes = [...responseTypes].sort();+ const paramTypeNames = [...paramTypes.keys()].sort();++ // Build client output+ const out: string[] = [];++ out.push(`// This file is auto-generated by scripts/generate-admin-client.ts`);+ out.push(`// Do not edit manually. Run: npm run generate:admin-client`);+ out.push(``);+ out.push(`import type { RequestFn, RequestOptions } from './request';`);+ out.push(`import { transformListParams } from './params';`);+ out.push(`import type {`);+ out.push(` PaginatedResponse,`);+ out.push(` ListParams,`);+ for (const t of importedTypes) {+ out.push(` ${t},`);+ }+ out.push(`} from './types';`);++ // Import param types from admin-params+ if (paramTypeNames.length > 0) {+ out.push(`import type {`);+ for (const name of paramTypeNames) {+ out.push(` ${name},`);+ }+ out.push(`} from './admin-params';`);+ }++ out.push(``);++ // Re-export param types so consumers can import from either file+ if (paramTypeNames.length > 0) {+ out.push(`export type {`);+ for (const name of paramTypeNames) {+ out.push(` ${name},`);+ }+ out.push(`} from './admin-params';`);+ out.push(``);+ }++ // Helper+ out.push(`/** Serialize expand arrays into comma-separated query params */`);+ out.push(`function getParams(params?: { expand?: string[] }): Record<string, string> | undefined {`);+ out.push(` if (!params?.expand?.length) return undefined;`);+ out.push(` return { expand: params.expand.join(',') };`);+ out.push(`}`);+ out.push(``);++ // Class+ out.push(`export class AdminClient {`);+ out.push(` private readonly request: RequestFn;`);+ out.push(``);+ out.push(` constructor(request: RequestFn) {`);+ out.push(` this.request = request;`);+ out.push(` }`);++ // Top-level resources+ for (const resource of topLevel) {+ const propName = camelCase(resource.name);+ const nestedResources = nested.filter((n) => n.parentName === resource.name);++ out.push(``);+ out.push(` // ============================================`);+ out.push(` // ${resource.tag}`);+ out.push(` // ============================================`);+ out.push(``);+ out.push(` readonly ${propName} = {`);+ out.push(generateResourceMethods(resource, paramTypes));++ // Add nested resources as sub-objects+ for (const nestedResource of nestedResources) {+ const nestedPropName = camelCase(nestedResource.name);+ out.push(` /** Nested: ${resource.name}/{id}/${nestedResource.name} */`);+ out.push(` ${nestedPropName}: {`);+ // Indent nested methods by 2 more spaces+ const nestedMethods = generateResourceMethods(nestedResource, paramTypes)+ .split('\n')+ .map((line) => (line.trim() ? ` ${line}` : line))+ .join('\n');+ out.push(nestedMethods);+ out.push(` },`);+ out.push(``);+ }++ out.push(` };`);+ }++ // Any orphan nested resources (parent not in spec yet)+ const orphanNested = nested.filter(+ (n) => !topLevel.some((t) => t.name === n.parentName)+ );+ for (const resource of orphanNested) {+ const propName = `${camelCase(resource.parentName!)}${singularPascal(resource.name).replace(/s$/, '')}s`;+ out.push(``);+ out.push(` // ============================================`);+ out.push(` // ${resource.tag} (nested under ${resource.parentName})`);+ out.push(` // ============================================`);+ out.push(``);+ out.push(` readonly ${propName} = {`);+ out.push(generateResourceMethods(resource, paramTypes));+ out.push(` };`);+ }++ out.push(`}`);+ out.push(``);++ return {+ client: out.join('\n'),+ params: generateParamsFile(paramTypes),+ };+}++// ---------------------------------------------------------------------------+// Main+// ---------------------------------------------------------------------------++const SPEC_PATH = path.resolve(import.meta.dirname, '../../../docs/api-reference/admin.yaml');+const OUTPUT_PATH = path.resolve(import.meta.dirname, '../src/admin-client.ts');+const PARAMS_PATH = path.resolve(import.meta.dirname, '../src/admin-params.ts');++if (!fs.existsSync(SPEC_PATH)) {+ console.error(`Admin API spec not found at: ${SPEC_PATH}`);+ console.error('Run `bundle exec rake rswag:specs:swaggerize` first to generate it.');+ process.exit(1);+}++console.log(`Reading: ${SPEC_PATH}`);+const yamlContent = fs.readFileSync(SPEC_PATH, 'utf-8');++// Use a proper YAML parser — try to import js-yaml or yaml, fall back to JSON conversion via CLI+let spec: OpenApiSpec;+try {+ // Try dynamic import of yaml (common in Node projects)+ const yamlModule = await import('yaml');+ spec = yamlModule.parse(yamlContent) as OpenApiSpec;+} catch {+ try {+ // Try js-yaml+ const jsYaml = await import('js-yaml');+ spec = jsYaml.load(yamlContent) as OpenApiSpec;+ } catch {+ // Last resort: use our minimal parser+ console.warn('No YAML parser found (yaml or js-yaml). Using minimal built-in parser.');+ spec = parseYaml(yamlContent) as OpenApiSpec;+ }+}++const { client, params } = generateClient(spec);++fs.writeFileSync(PARAMS_PATH, params, 'utf-8');+console.log(`Generated: ${PARAMS_PATH}`);++fs.writeFileSync(OUTPUT_PATH, client, 'utf-8');+console.log(`Generated: ${OUTPUT_PATH}`);++// Summary+const resources = analyzeResources(spec);+console.log(`\nResources (${resources.length}):`);+for (const r of resources) {+ const prefix = r.parentName ? ` └─ ${r.parentName}/{id}/` : ' ';+ console.log(`${prefix}${r.name} (${r.endpoints.map((e) => `${e.method} ${e.action}`).join(', ')})`);+}diff --git a/packages/sdk/src/admin-client.ts b/packages/sdk/src/admin-client.tsnew file mode 100644index 0000000000..7223e92a83--- /dev/null+++ b/packages/sdk/src/admin-client.ts@@ -0,0 +1,416 @@+// This file is auto-generated by scripts/generate-admin-client.ts+// Do not edit manually. Run: npm run generate:admin-client++import type { RequestFn, RequestOptions } from './request';+import { transformListParams } from './params';+import type {+ PaginatedResponse,+ ListParams,+ AdminAsset,+ AdminOptionType,+ AdminProduct,+ AdminTaxon,+ AdminTaxonomy,+ AdminVariant,+} from './types';+import type {+ AdminAssetCreateParams,+ AdminAssetUpdateParams,+ AdminOptionTypeCreateParams,+ AdminOptionTypeUpdateParams,+ AdminProductCreateParams,+ AdminProductUpdateParams,+ AdminTaxonCreateParams,+ AdminTaxonUpdateParams,+ AdminTaxonomyCreateParams,+ AdminTaxonomyUpdateParams,+ AdminVariantCreateParams,+ AdminVariantUpdateParams,+} from './admin-params';++export type {+ AdminAssetCreateParams,+ AdminAssetUpdateParams,+ AdminOptionTypeCreateParams,+ AdminOptionTypeUpdateParams,+ AdminProductCreateParams,+ AdminProductUpdateParams,+ AdminTaxonCreateParams,+ AdminTaxonUpdateParams,+ AdminTaxonomyCreateParams,+ AdminTaxonomyUpdateParams,+ AdminVariantCreateParams,+ AdminVariantUpdateParams,+} from './admin-params';++/** Serialize expand arrays into comma-separated query params */+function getParams(params?: { expand?: string[] }): Record<string, string> | undefined {+ if (!params?.expand?.length) return undefined;+ return { expand: params.expand.join(',') };+}++export class AdminClient {+ private readonly request: RequestFn;++ constructor(request: RequestFn) {+ this.request = request;+ }++ // ============================================+ // Option Types+ // ============================================++ readonly optionTypes = {+ /** List option types */+ list: (+ params?: ListParams,+ options?: RequestOptions+ ): Promise<PaginatedResponse<AdminOptionType>> =>+ this.request<PaginatedResponse<AdminOptionType>>('GET', '/option_types', {+ ...options,+ params: transformListParams({ ...params }),+ }),++ /** Create an option type */+ create: (+ params: AdminOptionTypeCreateParams,+ options?: RequestOptions+ ): Promise<AdminOptionType> =>+ this.request<AdminOptionType>('POST', '/option_types', {+ ...options,+ body: params,+ }),++ /** Get an option type */+ get: (+ id: string,+ params?: { expand?: string[] },+ options?: RequestOptions+ ): Promise<AdminOptionType> =>+ this.request<AdminOptionType>('GET', `/option_types/${id}`, {+ ...options,+ params: getParams(params),+ }),++ /** Update an option type */+ update: (+ id: string,+ params: AdminOptionTypeUpdateParams,+ options?: RequestOptions+ ): Promise<AdminOptionType> =>+ this.request<AdminOptionType>('PATCH', `/option_types/${id}`, {+ ...options,+ body: params,+ }),++ /** Delete an option type */+ delete: (+ id: string,+ options?: RequestOptions+ ): Promise<void> =>+ this.request<void>('DELETE', `/option_types/${id}`, options),++ };++ // ============================================+ // Products+ // ============================================++ readonly products = {+ /** List products */+ list: (+ params?: ListParams,+ options?: RequestOptions+ ): Promise<PaginatedResponse<AdminProduct>> =>+ this.request<PaginatedResponse<AdminProduct>>('GET', '/products', {+ ...options,+ params: transformListParams({ ...params }),+ }),++ /** Create a product */+ create: (+ params: AdminProductCreateParams,+ options?: RequestOptions+ ): Promise<AdminProduct> =>+ this.request<AdminProduct>('POST', '/products', {+ ...options,+ body: params,+ }),++ /** Get a product */+ get: (+ id: string,+ params?: { expand?: string[] },+ options?: RequestOptions+ ): Promise<AdminProduct> =>+ this.request<AdminProduct>('GET', `/products/${id}`, {+ ...options,+ params: getParams(params),+ }),++ /** Update a product */+ update: (+ id: string,+ params: AdminProductUpdateParams,+ options?: RequestOptions+ ): Promise<AdminProduct> =>+ this.request<AdminProduct>('PATCH', `/products/${id}`, {+ ...options,+ body: params,+ }),++ /** Delete a product */+ delete: (+ id: string,+ options?: RequestOptions+ ): Promise<void> =>+ this.request<void>('DELETE', `/products/${id}`, options),++ /** Nested: products/{id}/assets */+ assets: {+ /** List product assets */+ list: (+ productId: string,+ params?: ListParams,+ options?: RequestOptions+ ): Promise<PaginatedResponse<AdminAsset>> =>+ this.request<PaginatedResponse<AdminAsset>>('GET', `/products/${productId}/assets`, {+ ...options,+ params: transformListParams({ ...params }),+ }),++ /** Create an asset */+ create: (+ productId: string,+ params: AdminAssetCreateParams,+ options?: RequestOptions+ ): Promise<AdminAsset> =>+ this.request<AdminAsset>('POST', `/products/${productId}/assets`, {+ ...options,+ body: params,+ }),++ /** Update an asset */+ update: (+ productId: string,+ id: string,+ params: AdminAssetUpdateParams,+ options?: RequestOptions+ ): Promise<AdminAsset> =>+ this.request<AdminAsset>('PATCH', `/products/${productId}/assets/${id}`, {+ ...options,+ body: params,+ }),++ /** Delete an asset */+ delete: (+ productId: string,+ id: string,+ options?: RequestOptions+ ): Promise<void> =>+ this.request<void>('DELETE', `/products/${productId}/assets/${id}`, options),++ },++ /** Nested: products/{id}/variants */+ variants: {+ /** List product variants */+ list: (+ productId: string,+ params?: ListParams,+ options?: RequestOptions+ ): Promise<PaginatedResponse<AdminVariant>> =>+ this.request<PaginatedResponse<AdminVariant>>('GET', `/products/${productId}/variants`, {+ ...options,+ params: transformListParams({ ...params }),+ }),++ /** Create a variant */+ create: (+ productId: string,+ params: AdminVariantCreateParams,+ options?: RequestOptions+ ): Promise<AdminVariant> =>+ this.request<AdminVariant>('POST', `/products/${productId}/variants`, {+ ...options,+ body: params,+ }),++ /** Get a variant */+ get: (+ productId: string,+ id: string,+ params?: { expand?: string[] },+ options?: RequestOptions+ ): Promise<AdminVariant> =>+ this.request<AdminVariant>('GET', `/products/${productId}/variants/${id}`, {+ ...options,+ params: getParams(params),+ }),++ /** Update a variant */+ update: (+ productId: string,+ id: string,+ params: AdminVariantUpdateParams,+ options?: RequestOptions+ ): Promise<AdminVariant> =>+ this.request<AdminVariant>('PATCH', `/products/${productId}/variants/${id}`, {+ ...options,+ body: params,+ }),++ /** Delete a variant */+ delete: (+ productId: string,+ id: string,+ options?: RequestOptions+ ): Promise<void> =>+ this.request<void>('DELETE', `/products/${productId}/variants/${id}`, options),++ },++ };++ // ============================================+ // Taxonomies+ // ============================================++ readonly taxonomies = {+ /** List taxonomies */+ list: (+ params?: ListParams,+ options?: RequestOptions+ ): Promise<PaginatedResponse<AdminTaxonomy>> =>+ this.request<PaginatedResponse<AdminTaxonomy>>('GET', '/taxonomies', {+ ...options,+ params: transformListParams({ ...params }),+ }),++ /** Create a taxonomy */+ create: (+ params: AdminTaxonomyCreateParams,+ options?: RequestOptions+ ): Promise<AdminTaxonomy> =>+ this.request<AdminTaxonomy>('POST', '/taxonomies', {+ ...options,+ body: params,+ }),++ /** Get a taxonomy */+ get: (+ id: string,+ params?: { expand?: string[] },+ options?: RequestOptions+ ): Promise<AdminTaxonomy> =>+ this.request<AdminTaxonomy>('GET', `/taxonomies/${id}`, {+ ...options,+ params: getParams(params),+ }),++ /** Update a taxonomy */+ update: (+ id: string,+ params: AdminTaxonomyUpdateParams,+ options?: RequestOptions+ ): Promise<AdminTaxonomy> =>+ this.request<AdminTaxonomy>('PATCH', `/taxonomies/${id}`, {+ ...options,+ body: params,+ }),++ /** Delete a taxonomy */+ delete: (+ id: string,+ options?: RequestOptions+ ): Promise<void> =>+ this.request<void>('DELETE', `/taxonomies/${id}`, options),++ /** Nested: taxonomies/{id}/taxons */+ taxons: {+ /** List taxonomy taxons */+ list: (+ taxonomyId: string,+ params?: ListParams,+ options?: RequestOptions+ ): Promise<PaginatedResponse<AdminTaxon>> =>+ this.request<PaginatedResponse<AdminTaxon>>('GET', `/taxonomies/${taxonomyId}/taxons`, {+ ...options,+ params: transformListParams({ ...params }),+ }),++ /** Create a taxon */+ create: (+ taxonomyId: string,+ params: AdminTaxonCreateParams,+ options?: RequestOptions+ ): Promise<AdminTaxon> =>+ this.request<AdminTaxon>('POST', `/taxonomies/${taxonomyId}/taxons`, {+ ...options,+ body: params,+ }),++ /** Get a taxonomy taxon */+ get: (+ taxonomyId: string,+ id: string,+ params?: { expand?: string[] },+ options?: RequestOptions+ ): Promise<AdminTaxon> =>+ this.request<AdminTaxon>('GET', `/taxonomies/${taxonomyId}/taxons/${id}`, {+ ...options,+ params: getParams(params),+ }),++ /** Update a taxon */+ update: (+ taxonomyId: string,+ id: string,+ params: AdminTaxonUpdateParams,+ options?: RequestOptions+ ): Promise<AdminTaxon> =>+ this.request<AdminTaxon>('PATCH', `/taxonomies/${taxonomyId}/taxons/${id}`, {+ ...options,+ body: params,+ }),++ /** Delete a taxon */+ delete: (+ taxonomyId: string,+ id: string,+ options?: RequestOptions+ ): Promise<void> =>+ this.request<void>('DELETE', `/taxonomies/${taxonomyId}/taxons/${id}`, options),++ },++ };++ // ============================================+ // Taxons+ // ============================================++ readonly taxons = {+ /** List taxons */+ list: (+ params?: ListParams,+ options?: RequestOptions+ ): Promise<PaginatedResponse<AdminTaxon>> =>+ this.request<PaginatedResponse<AdminTaxon>>('GET', '/taxons', {+ ...options,+ params: transformListParams({ ...params }),+ }),++ /** Get a taxon */+ get: (+ id: string,+ params?: { expand?: string[] },+ options?: RequestOptions+ ): Promise<AdminTaxon> =>+ this.request<AdminTaxon>('GET', `/taxons/${id}`, {+ ...options,+ params: getParams(params),+ }),++ };+}diff --git a/packages/sdk/src/admin-params.ts b/packages/sdk/src/admin-params.tsnew file mode 100644index 0000000000..3032351c84--- /dev/null+++ b/packages/sdk/src/admin-params.ts@@ -0,0 +1,190 @@+// This file is auto-generated by scripts/generate-admin-client.ts+// Do not edit manually. Run: npm run generate:admin-client++// Request parameter types (generated from OpenAPI request bodies)++export interface AdminAssetCreateParams {+ alt?: string;+ position?: number;+ type?: string;+ viewable_type?: string;+ viewable_id?: string;+}++export interface AdminAssetUpdateParams {+ alt?: string;+ position?: number;+}++export interface AdminOptionTypeCreateParams {+ name: string;+ presentation: string;+ position?: number;+ filterable?: boolean;+ option_values?: Array<{+ name?: string;+ presentation?: string;+ position?: number;+ }>;+}++export interface AdminOptionTypeUpdateParams {+ name?: string;+ presentation?: string;+ position?: number;+ filterable?: boolean;+ option_values?: Array<{+ id?: string;+ name?: string;+ presentation?: string;+ position?: number;+ }>;+}++export interface AdminProductCreateParams {+ name: string;+ price: number;+ description?: string;+ slug?: string;+ status?: 'draft' | 'active' | 'archived';+ sku?: string;+ shipping_category_id: string;+ tax_category_id?: string;+ taxon_ids?: Array<string>;+ tags?: Array<string>;+ variants?: Array<{+ sku?: string;+ price?: number;+ option_type?: string;+ option_value?: string;+ total_on_hand?: number;+ prices?: Array<{+ currency: string;+ amount: number;+ compare_at_amount?: number;+ }>;+ }>;+}++export interface AdminProductUpdateParams {+ name?: string;+ price?: number;+ description?: string;+ slug?: string;+ status?: 'draft' | 'active' | 'archived';+ sku?: string;+ shipping_category_id?: string;+ tax_category_id?: string;+ taxon_ids?: Array<string>;+ tags?: Array<string>;+ variants?: Array<{+ sku?: string;+ price?: number;+ option_type?: string;+ option_value?: string;+ total_on_hand?: number;+ prices?: Array<{+ currency: string;+ amount: number;+ compare_at_amount?: number;+ }>;+ }>;+}++export interface AdminTaxonomyCreateParams {+ name: string;+ position?: number;+}++export interface AdminTaxonomyUpdateParams {+ name?: string;+ position?: number;+}++export interface AdminTaxonCreateParams {+ name: string;+ parent_id?: string;+ position?: number;+ description?: string;+ permalink?: string;+ meta_title?: string;+ meta_description?: string;+ meta_keywords?: string;+ hide_from_nav?: boolean;+ sort_order?: string;+}++export interface AdminTaxonUpdateParams {+ name?: string;+ parent_id?: string;+ position?: number;+ description?: string;+ permalink?: string;+ meta_title?: string;+ meta_description?: string;+ meta_keywords?: string;+ hide_from_nav?: boolean;+ sort_order?: string;+}++export interface AdminVariantCreateParams {+ sku?: string;+ price?: number;+ compare_at_price?: number;+ cost_price?: number;+ cost_currency?: string;+ weight?: number;+ height?: number;+ width?: number;+ depth?: number;+ weight_unit?: string;+ dimensions_unit?: string;+ track_inventory?: boolean;+ tax_category_id?: string;+ option_type?: string;+ option_value?: string;+ total_on_hand?: number;+ position?: number;+ barcode?: string;+ prices?: Array<{+ currency: string;+ amount: number;+ compare_at_amount?: number;+ }>;+ stock_items?: Array<{+ stock_location_id?: string;+ count_on_hand?: number;+ backorderable?: boolean;+ }>;+}++export interface AdminVariantUpdateParams {+ sku?: string;+ price?: number;+ compare_at_price?: number;+ cost_price?: number;+ cost_currency?: string;+ weight?: number;+ height?: number;+ width?: number;+ depth?: number;+ weight_unit?: string;+ dimensions_unit?: string;+ track_inventory?: boolean;+ tax_category_id?: string;+ option_type?: string;+ option_value?: string;+ total_on_hand?: number;+ position?: number;+ barcode?: string;+ prices?: Array<{+ currency: string;+ amount: number;+ compare_at_amount?: number;+ }>;+ stock_items?: Array<{+ stock_location_id?: string;+ count_on_hand?: number;+ backorderable?: boolean;+ }>;+}diff --git a/packages/sdk/src/types/generated/AdminAsset.ts b/packages/sdk/src/types/generated/AdminAsset.tsnew file mode 100644index 0000000000..45b82d43ef--- /dev/null+++ b/packages/sdk/src/types/generated/AdminAsset.ts@@ -0,0 +1,16 @@+// Typelizer digest a7131b5cb9f49b608c80755fa4863817+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++type AdminAsset = {+ id: string;+ viewable_id: string;+ type: string | null;+ viewable_type: string;+ position: number | null;+ alt: string | null;+ created_at: string;+ updated_at: string;+}++export default AdminAsset;diff --git a/packages/sdk/src/types/generated/AdminImage.ts b/packages/sdk/src/types/generated/AdminImage.tsnew file mode 100644index 0000000000..2735e44deb--- /dev/null+++ b/packages/sdk/src/types/generated/AdminImage.ts@@ -0,0 +1,23 @@+// Typelizer digest 26aed2c59bca4ed6fe0215e853e49051+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++type AdminImage = {+ id: string;+ viewable_id: string;+ type: string | null;+ viewable_type: string;+ position: number | null;+ alt: string | null;+ created_at: string;+ updated_at: string;+ original_url: string | null;+ mini_url: string | null;+ small_url: string | null;+ medium_url: string | null;+ large_url: string | null;+ xlarge_url: string | null;+ og_image_url: string | null;+}++export default AdminImage;diff --git a/packages/sdk/src/types/generated/AdminOptionType.ts b/packages/sdk/src/types/generated/AdminOptionType.tsindex 628c3db647..9d190ff565 100644--- a/packages/sdk/src/types/generated/AdminOptionType.ts+++ b/packages/sdk/src/types/generated/AdminOptionType.ts@@ -1,7 +1,7 @@-// Typelizer digest e080964a17d87cba0fd4d11492b024d3+// Typelizer digest a7efca28d62f1698caf3707d1f3ac47c//// DO NOT MODIFY: This file was automatically generated by Typelizer.-import type {StoreOptionValue} from '@/types'+import type {AdminOptionValue} from '@/types'type AdminOptionType = {id: string;@@ -9,7 +9,7 @@ type AdminOptionType = {presentation: string;position: number;filterable: boolean;- option_values: Array<StoreOptionValue>;+ option_values: Array<AdminOptionValue>;}export default AdminOptionType;diff --git a/packages/sdk/src/types/generated/AdminOptionValue.ts b/packages/sdk/src/types/generated/AdminOptionValue.tsnew file mode 100644index 0000000000..8bc23d1ef7--- /dev/null+++ b/packages/sdk/src/types/generated/AdminOptionValue.ts@@ -0,0 +1,15 @@+// Typelizer digest a7b00b94654d389e1164456bbdbd0a34+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++type AdminOptionValue = {+ id: string;+ option_type_id: string;+ name: string;+ presentation: string;+ position: number;+ option_type_name: string;+ option_type_presentation: string;+}++export default AdminOptionValue;diff --git a/packages/sdk/src/types/generated/AdminStockItem.ts b/packages/sdk/src/types/generated/AdminStockItem.tsnew file mode 100644index 0000000000..c50304fc20--- /dev/null+++ b/packages/sdk/src/types/generated/AdminStockItem.ts@@ -0,0 +1,15 @@+// Typelizer digest 9c4f032acac9fb41e7def59c1b9e9d30+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++type AdminStockItem = {+ id: string;+ count_on_hand: number;+ backorderable: boolean;+ created_at: string;+ updated_at: string;+ stock_location_id: string | null;+ variant_id: string | null;+}++export default AdminStockItem;diff --git a/packages/sdk/src/types/generated/AdminTaxonomy.ts b/packages/sdk/src/types/generated/AdminTaxonomy.tsnew file mode 100644index 0000000000..d82da46883--- /dev/null+++ b/packages/sdk/src/types/generated/AdminTaxonomy.ts@@ -0,0 +1,18 @@+// Typelizer digest 9bdfc6ed80d686884a358a8d0e25bb7f+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.+import type {AdminTaxon, AdminMetafield} from '@/types'++type AdminTaxonomy = {+ id: string;+ name: string;+ position: number;+ created_at: string;+ updated_at: string;+ root_id: string | null;+ root?: AdminTaxon;+ taxons?: Array<AdminTaxon>;+ metafields?: Array<AdminMetafield>;+}++export default AdminTaxonomy;diff --git a/packages/sdk/src/zod/generated/AdminAsset.ts b/packages/sdk/src/zod/generated/AdminAsset.tsnew file mode 100644index 0000000000..15c7705261--- /dev/null+++ b/packages/sdk/src/zod/generated/AdminAsset.ts@@ -0,0 +1,15 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';++export const AdminAssetSchema = z.object({+ id: z.string(),+ viewable_id: z.string(),+ type: z.string().nullable(),+ viewable_type: z.string(),+ position: z.number().nullable(),+ alt: z.string().nullable(),+ created_at: z.string(),+ updated_at: z.string(),+});++export type AdminAsset = z.infer<typeof AdminAssetSchema>;diff --git a/packages/sdk/src/zod/generated/AdminImage.ts b/packages/sdk/src/zod/generated/AdminImage.tsnew file mode 100644index 0000000000..92c1b02c4e--- /dev/null+++ b/packages/sdk/src/zod/generated/AdminImage.ts@@ -0,0 +1,22 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';++export const AdminImageSchema = z.object({+ id: z.string(),+ viewable_id: z.string(),+ type: z.string().nullable(),+ viewable_type: z.string(),+ position: z.number().nullable(),+ alt: z.string().nullable(),+ created_at: z.string(),+ updated_at: z.string(),+ original_url: z.string().nullable(),+ mini_url: z.string().nullable(),+ small_url: z.string().nullable(),+ medium_url: z.string().nullable(),+ large_url: z.string().nullable(),+ xlarge_url: z.string().nullable(),+ og_image_url: z.string().nullable(),+});++export type AdminImage = z.infer<typeof AdminImageSchema>;diff --git a/packages/sdk/src/zod/generated/AdminOptionType.ts b/packages/sdk/src/zod/generated/AdminOptionType.tsindex b703fdd411..d869007cb3 100644--- a/packages/sdk/src/zod/generated/AdminOptionType.ts+++ b/packages/sdk/src/zod/generated/AdminOptionType.ts@@ -1,6 +1,6 @@// This file is auto-generated. Do not edit directly.import { z } from 'zod';-import { StoreOptionValueSchema } from './StoreOptionValue';+import { AdminOptionValueSchema } from './AdminOptionValue';export const AdminOptionTypeSchema = z.object({id: z.string(),@@ -8,7 +8,7 @@ export const AdminOptionTypeSchema = z.object({presentation: z.string(),position: z.number(),filterable: z.boolean(),- option_values: z.array(StoreOptionValueSchema),+ option_values: z.array(AdminOptionValueSchema),});export type AdminOptionType = z.infer<typeof AdminOptionTypeSchema>;diff --git a/packages/sdk/src/zod/generated/AdminOptionValue.ts b/packages/sdk/src/zod/generated/AdminOptionValue.tsnew file mode 100644index 0000000000..e10bd1f810--- /dev/null+++ b/packages/sdk/src/zod/generated/AdminOptionValue.ts@@ -0,0 +1,14 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';++export const AdminOptionValueSchema = z.object({+ id: z.string(),+ option_type_id: z.string(),+ name: z.string(),+ presentation: z.string(),+ position: z.number(),+ option_type_name: z.string(),+ option_type_presentation: z.string(),+});++export type AdminOptionValue = z.infer<typeof AdminOptionValueSchema>;diff --git a/packages/sdk/src/zod/generated/AdminProduct.ts b/packages/sdk/src/zod/generated/AdminProduct.tsnew file mode 100644index 0000000000..e495c31a40--- /dev/null+++ b/packages/sdk/src/zod/generated/AdminProduct.ts@@ -0,0 +1,45 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';+import { AdminImageSchema } from './AdminImage';+import { AdminMetafieldSchema } from './AdminMetafield';+import { AdminOptionTypeSchema } from './AdminOptionType';+import { AdminPriceSchema } from './AdminPrice';+import { AdminTaxonSchema } from './AdminTaxon';+import { AdminVariantSchema } from './AdminVariant';++export const AdminProductSchema = z.object({+ id: z.string(),+ name: z.string(),+ description: z.string().nullable(),+ slug: z.string(),+ meta_description: z.string().nullable(),+ meta_keywords: z.string().nullable(),+ variant_count: z.number(),+ available_on: z.string().nullable(),+ created_at: z.string(),+ updated_at: z.string(),+ purchasable: z.boolean(),+ in_stock: z.boolean(),+ backorderable: z.boolean(),+ available: z.boolean(),+ default_variant_id: z.string(),+ thumbnail_url: z.string().nullable(),+ tags: z.array(z.string()),+ price: AdminPriceSchema,+ original_price: AdminPriceSchema.nullable(),+ images: z.array(AdminImageSchema).optional(),+ variants: z.array(AdminVariantSchema).optional(),+ default_variant: AdminVariantSchema.optional(),+ master_variant: AdminVariantSchema.optional(),+ option_types: z.array(AdminOptionTypeSchema).optional(),+ taxons: z.array(z.lazy(() => AdminTaxonSchema)).optional(),+ metafields: z.array(AdminMetafieldSchema).optional(),+ status: z.string(),+ make_active_at: z.string().nullable(),+ discontinue_on: z.string().nullable(),+ deleted_at: z.string().nullable(),+ cost_price: z.string().nullable(),+ cost_currency: z.string().nullable(),+});++export type AdminProduct = z.infer<typeof AdminProductSchema>;diff --git a/packages/sdk/src/zod/generated/AdminStockItem.ts b/packages/sdk/src/zod/generated/AdminStockItem.tsnew file mode 100644index 0000000000..97dd277872--- /dev/null+++ b/packages/sdk/src/zod/generated/AdminStockItem.ts@@ -0,0 +1,14 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';++export const AdminStockItemSchema = z.object({+ id: z.string(),+ count_on_hand: z.number(),+ backorderable: z.boolean(),+ created_at: z.string(),+ updated_at: z.string(),+ stock_location_id: z.string().nullable(),+ variant_id: z.string().nullable(),+});++export type AdminStockItem = z.infer<typeof AdminStockItemSchema>;diff --git a/packages/sdk/src/zod/generated/AdminTaxonomy.ts b/packages/sdk/src/zod/generated/AdminTaxonomy.tsnew file mode 100644index 0000000000..e5cb990048--- /dev/null+++ b/packages/sdk/src/zod/generated/AdminTaxonomy.ts@@ -0,0 +1,18 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';+import { AdminMetafieldSchema } from './AdminMetafield';+import { AdminTaxonSchema } from './AdminTaxon';++export const AdminTaxonomySchema = 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(() => AdminTaxonSchema).optional(),+ taxons: z.array(z.lazy(() => AdminTaxonSchema)).optional(),+ metafields: z.array(AdminMetafieldSchema).optional(),+});++export type AdminTaxonomy = z.infer<typeof AdminTaxonomySchema>;diff --git a/packages/sdk/src/zod/generated/AdminVariant.ts b/packages/sdk/src/zod/generated/AdminVariant.tsnew file mode 100644index 0000000000..713b4d4c3d--- /dev/null+++ b/packages/sdk/src/zod/generated/AdminVariant.ts@@ -0,0 +1,42 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';+import { AdminImageSchema } from './AdminImage';+import { AdminMetafieldSchema } from './AdminMetafield';+import { AdminOptionValueSchema } from './AdminOptionValue';+import { AdminPriceSchema } from './AdminPrice';+import { AdminStockItemSchema } from './AdminStockItem';++export const AdminVariantSchema = z.object({+ id: z.string(),+ product_id: z.string(),+ sku: z.string().nullable(),+ is_master: z.boolean(),+ options_text: z.string(),+ track_inventory: z.boolean(),+ image_count: z.number(),+ created_at: z.string(),+ updated_at: z.string(),+ thumbnail: z.string().nullable(),+ purchasable: z.boolean(),+ in_stock: z.boolean(),+ backorderable: z.boolean(),+ weight: z.number().nullable(),+ height: z.number().nullable(),+ width: z.number().nullable(),+ depth: z.number().nullable(),+ price: AdminPriceSchema,+ original_price: AdminPriceSchema.nullable(),+ images: z.array(AdminImageSchema).optional(),+ option_values: z.array(AdminOptionValueSchema),+ metafields: z.array(AdminMetafieldSchema).optional(),+ position: z.number(),+ tax_category_id: z.string().nullable(),+ cost_price: z.string().nullable(),+ cost_currency: z.string().nullable(),+ deleted_at: z.string().nullable(),+ total_on_hand: z.number().nullable(),+ prices: z.array(AdminPriceSchema).optional(),+ stock_items: z.array(AdminStockItemSchema).optional(),+});++export type AdminVariant = z.infer<typeof AdminVariantSchema>;diff --git a/spree/api/app/controllers/spree/api/v3/admin/products/assets_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/products/assets_controller.rbindex a54b847765..863c6e28da 100644--- a/spree/api/app/controllers/spree/api/v3/admin/products/assets_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/products/assets_controller.rb@@ -22,16 +22,17 @@ module Spreeenddef serializer_class- Spree.api.image_serializer+ Spree.api.admin_asset_serializerenddef set_parent- @parent = current_store.products.find_by_prefix_id!(params[:product_id])- authorize!(:show, @parent)+ @product = current_store.products.find_by_prefix_id!(params[:product_id])+ authorize!(:show, @product)+ @parent = @product.masterenddef parent_association- :assets+ :imagesenddef build_resource@@ -42,10 +43,8 @@ module Spreeraise ArgumentError, "Invalid asset type: #{asset_type}"end- # Build through parent association, then set the correct STI type- asset = @parent.assets.build(permitted_params.except(:type, :variant_ids))+ asset = @parent.images.build(permitted_params.except(:type, :variant_ids))asset.type = asset_class.name- asset.viewable = @parent.master if asset.viewable.nil?assetenddiff --git a/spree/api/app/controllers/spree/api/v3/admin/variants/prices_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/variants/prices_controller.rbdeleted file mode 100644index 2647f4c52b..0000000000--- a/spree/api/app/controllers/spree/api/v3/admin/variants/prices_controller.rb+++ /dev/null@@ -1,30 +0,0 @@-module Spree- module Api- module V3- module Admin- module Variants- class PricesController < ResourceController- protected-- def model_class- Spree::Price- end-- def serializer_class- Spree.api.admin_price_serializer- end-- def set_parent- @parent = current_store.variants.find_by_prefix_id!(params[:variant_id])- authorize!(:show, @parent.product)- end-- def parent_association- :prices- end- end- end- end- end- end-enddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex b8382f2305..59df23eeb4 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -100,11 +100,6 @@ Spree::Core::Engine.add_routes doresources :assets, controller: 'products/assets', only: [:index, :create, :update, :destroy]end- # Variants > Prices- resources :variants, only: [] do- resources :prices, controller: 'variants/prices', only: [:index, :create, :update, :destroy]- end-# Taxonomies > Taxonsresources :taxonomies doresources :taxons, controller: 'taxonomies/taxons'diff --git a/spree/api/spec/integration/spree/api/v3/admin/assets_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/assets_spec.rbnew file mode 100644index 0000000000..d8338e9aa0--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/admin/assets_spec.rb@@ -0,0 +1,125 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Admin Assets API', type: :request, swagger_doc: 'api-reference/admin.yaml' do+ include_context 'API v3 Admin'++ let!(:product) { create(:product, stores: [store]) }+ let!(:image) { create(:image, viewable: product.master) }+ let(:Authorization) { "Bearer #{admin_jwt_token}" }++ path '/api/v3/admin/products/{product_id}/assets' do+ get 'List product assets' do+ tags 'Assets'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a paginated list of assets (images) for a product.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'++ response '200', 'assets found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:product_id) { product.prefixed_id }++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['data']).to be_an(Array)+ end+ end+ end++ post 'Create an asset' do+ tags 'Assets'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Creates a new asset (image) for a product.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ alt: { type: :string, example: 'Product front view' },+ position: { type: :integer, example: 1 },+ type: { type: :string, example: 'Spree::Image', description: 'Asset type (defaults to Spree::Image)' },+ viewable_type: { type: :string, description: 'Polymorphic viewable type' },+ viewable_id: { type: :string, description: 'Polymorphic viewable ID' }+ }+ }++ response '422', 'validation error (attachment required)' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:product_id) { product.prefixed_id }+ let(:body) { { alt: 'New product image', position: 1 } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ path '/api/v3/admin/products/{product_id}/assets/{id}' do+ patch 'Update an asset' do+ tags 'Assets'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Updates an asset. Only provided fields are updated.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Asset prefixed ID'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ alt: { type: :string, example: 'Updated alt text' },+ position: { type: :integer, example: 2 }+ }+ }++ response '200', 'asset updated' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:product_id) { product.prefixed_id }+ let(:id) { image.prefixed_id }+ let(:body) { { alt: 'Updated alt text' } }++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['alt']).to eq('Updated alt text')+ end+ end+ end++ delete 'Delete an asset' do+ tags 'Assets'+ security [api_key: [], bearer_auth: []]+ description 'Deletes an asset from a product.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Asset prefixed ID'++ response '204', 'asset deleted' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:product_id) { product.prefixed_id }+ let(:id) { image.prefixed_id }++ run_test!+ end+ end+ end+enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/option_types_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/option_types_spec.rbnew file mode 100644index 0000000000..382a964f02--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/admin/option_types_spec.rb@@ -0,0 +1,216 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Admin Option Types API', type: :request, swagger_doc: 'api-reference/admin.yaml' do+ include_context 'API v3 Admin'++ let!(:option_type) { create(:option_type) }+ let(:Authorization) { "Bearer #{admin_jwt_token}" }++ path '/api/v3/admin/option_types' do+ get 'List option types' do+ tags 'Option Types'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a paginated list of option types.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'+ parameter name: :'q[name_cont]', in: :query, type: :string, required: false,+ description: 'Filter by name (contains)'++ response '200', 'option types found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }++ schema SwaggerSchemaHelpers.paginated('AdminOptionType')++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['data']).to be_an(Array)+ expect(data['data'].length).to be >= 1+ end+ end++ response '401', 'unauthorized' do+ let(:'x-spree-api-key') { 'invalid' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ post 'Create an option type' do+ tags 'Option Types'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description <<~DESC+ Creates a new option type. Supports nested option values.++ Option values can be provided inline and will be created or updated by name.+ DESC++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ name: { type: :string, example: 'color' },+ presentation: { type: :string, example: 'Color' },+ position: { type: :integer, example: 1 },+ filterable: { type: :boolean, example: true },+ option_values: {+ type: :array,+ items: {+ type: :object,+ properties: {+ name: { type: :string, example: 'red' },+ presentation: { type: :string, example: 'Red' },+ position: { type: :integer }+ }+ }+ }+ },+ required: %w[name presentation]+ }++ response '201', 'option type created' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:body) { { name: 'material', presentation: 'Material' } }++ schema '$ref' => '#/components/schemas/AdminOptionType'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['name']).to eq('material')+ expect(data['presentation']).to eq('Material')+ end+ end++ response '422', 'validation error' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:body) { { name: '', presentation: '' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ path '/api/v3/admin/option_types/{id}' do+ get 'Get an option type' do+ tags 'Option Types'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a single option type by prefixed ID, including its option values.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Option type prefixed ID'++ response '200', 'option type found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { option_type.prefixed_id }++ schema '$ref' => '#/components/schemas/AdminOptionType'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['id']).to eq(option_type.prefixed_id)+ end+ end++ response '404', 'option type not found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { 'ot_nonexistent' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ patch 'Update an option type' do+ tags 'Option Types'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Updates an option type. Supports updating nested option values.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Option type prefixed ID'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ name: { type: :string, example: 'color' },+ presentation: { type: :string, example: 'Color' },+ position: { type: :integer, example: 1 },+ filterable: { type: :boolean, example: true },+ option_values: {+ type: :array,+ items: {+ type: :object,+ properties: {+ id: { type: :string, description: 'Existing option value ID to update' },+ name: { type: :string, example: 'red' },+ presentation: { type: :string, example: 'Red' },+ position: { type: :integer }+ }+ }+ }+ }+ }++ response '200', 'option type updated' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { option_type.prefixed_id }+ let(:body) { { presentation: 'Updated Presentation' } }++ schema '$ref' => '#/components/schemas/AdminOptionType'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['presentation']).to eq('Updated Presentation')+ end+ end++ response '422', 'validation error' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { option_type.prefixed_id }+ let(:body) { { presentation: '' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ delete 'Delete an option type' do+ tags 'Option Types'+ security [api_key: [], bearer_auth: []]+ description 'Deletes an option type.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Option type prefixed ID'++ response '204', 'option type deleted' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { option_type.prefixed_id }++ run_test!+ end+ end+ end+enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/products_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/products_spec.rbnew file mode 100644index 0000000000..7b82addcd7--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/admin/products_spec.rb@@ -0,0 +1,266 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Admin Products API', type: :request, swagger_doc: 'api-reference/admin.yaml' do+ include_context 'API v3 Admin'++ let!(:product) { create(:product, stores: [store]) }+ let(:shipping_category) { create(:shipping_category) }+ let(:Authorization) { "Bearer #{admin_jwt_token}" }++ path '/api/v3/admin/products' do+ get 'List products' do+ tags 'Products'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a paginated list of products for the current store.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'+ parameter name: :sort, in: :query, type: :string, required: false,+ description: 'Sort field (e.g., name, -name, price, -price, best_selling)'+ parameter name: :expand, in: :query, type: :string, required: false,+ description: 'Comma-separated associations to expand (e.g., variants, variants.images)'+ parameter name: :'q[name_cont]', in: :query, type: :string, required: false,+ description: 'Filter by name (contains)'+ parameter name: :'q[status_eq]', in: :query, type: :string, required: false,+ description: 'Filter by status'++ response '200', 'products found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }++ schema SwaggerSchemaHelpers.paginated('AdminProduct')++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['data']).to be_an(Array)+ expect(data['meta']).to include('page', 'limit', 'count', 'pages')+ end+ end++ response '401', 'unauthorized' do+ let(:'x-spree-api-key') { 'invalid' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ post 'Create a product' do+ tags 'Products'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description <<~DESC+ Creates a new product. Supports nested variants with prices and option types.++ Option types and values are auto-created if they don't exist.+ Prices are upserted by currency. Stock items are upserted by stock location.+ DESC++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ name: { type: :string, example: 'Premium T-Shirt' },+ price: { type: :number, example: 29.99 },+ description: { type: :string },+ slug: { type: :string },+ status: { type: :string, enum: %w[draft active archived] },+ sku: { type: :string },+ shipping_category_id: { type: :string, description: 'Prefixed ID (e.g., sc_xxx) or integer' },+ tax_category_id: { type: :string, description: 'Prefixed ID or integer' },+ taxon_ids: { type: :array, items: { type: :string }, description: 'Array of prefixed taxon IDs' },+ tags: { type: :array, items: { type: :string }, example: %w[eco sale] },+ variants: {+ type: :array,+ items: {+ type: :object,+ properties: {+ sku: { type: :string },+ price: { type: :number },+ option_type: { type: :string, example: 'Size' },+ option_value: { type: :string, example: 'Small' },+ total_on_hand: { type: :integer },+ prices: {+ type: :array,+ items: {+ type: :object,+ properties: {+ currency: { type: :string, example: 'USD' },+ amount: { type: :number, example: 29.99 },+ compare_at_amount: { type: :number, example: 39.99 }+ },+ required: %w[currency amount]+ }+ }+ }+ }+ }+ },+ required: %w[name price shipping_category_id]+ }++ response '201', 'product created' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:body) { { name: 'New Product', price: 19.99, shipping_category_id: shipping_category.id } }++ schema '$ref' => '#/components/schemas/AdminProduct'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['name']).to eq('New Product')+ end+ end++ response '422', 'validation error' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:body) { { name: '' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ path '/api/v3/admin/products/{id}' do+ get 'Get a product' do+ tags 'Products'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a single product by prefixed ID.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Product prefixed ID (e.g., prod_xxx)'+ parameter name: :expand, in: :query, type: :string, required: false,+ description: 'Comma-separated associations to expand (e.g., variants)'++ response '200', 'product found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { product.prefixed_id }++ schema '$ref' => '#/components/schemas/AdminProduct'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['id']).to eq(product.prefixed_id)+ end+ end++ response '404', 'product not found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { 'prod_nonexistent' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ patch 'Update a product' do+ tags 'Products'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Updates a product. Only provided fields are updated.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ name: { type: :string, example: 'Premium T-Shirt' },+ price: { type: :number, example: 29.99 },+ description: { type: :string },+ slug: { type: :string },+ status: { type: :string, enum: %w[draft active archived] },+ sku: { type: :string },+ shipping_category_id: { type: :string, description: 'Prefixed ID (e.g., sc_xxx) or integer' },+ tax_category_id: { type: :string, description: 'Prefixed ID or integer' },+ taxon_ids: { type: :array, items: { type: :string }, description: 'Array of prefixed taxon IDs' },+ tags: { type: :array, items: { type: :string }, example: %w[eco sale] },+ variants: {+ type: :array,+ items: {+ type: :object,+ properties: {+ sku: { type: :string },+ price: { type: :number },+ option_type: { type: :string, example: 'Size' },+ option_value: { type: :string, example: 'Small' },+ total_on_hand: { type: :integer },+ prices: {+ type: :array,+ items: {+ type: :object,+ properties: {+ currency: { type: :string, example: 'USD' },+ amount: { type: :number, example: 29.99 },+ compare_at_amount: { type: :number, example: 39.99 }+ },+ required: %w[currency amount]+ }+ }+ }+ }+ }+ }+ }++ response '200', 'product updated' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { product.prefixed_id }+ let(:body) { { name: 'Updated Name' } }++ schema '$ref' => '#/components/schemas/AdminProduct'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['name']).to eq('Updated Name')+ end+ end++ response '422', 'validation error' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { product.prefixed_id }+ let(:body) { { name: '' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ delete 'Delete a product' do+ tags 'Products'+ security [api_key: [], bearer_auth: []]+ description 'Soft-deletes a product.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Product prefixed ID'++ response '204', 'product deleted' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { product.prefixed_id }++ run_test! do+ expect(product.reload.deleted_at).not_to be_nil+ end+ end+ end+ end+enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/taxonomies_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/taxonomies_spec.rbnew file mode 100644index 0000000000..67f8cd45ad--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/admin/taxonomies_spec.rb@@ -0,0 +1,184 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Admin Taxonomies API', type: :request, swagger_doc: 'api-reference/admin.yaml' do+ include_context 'API v3 Admin'++ let!(:taxonomy) { create(:taxonomy, store: store) }+ let(:Authorization) { "Bearer #{admin_jwt_token}" }++ path '/api/v3/admin/taxonomies' do+ get 'List taxonomies' do+ tags 'Taxonomies'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a paginated list of taxonomies for the current store.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'++ response '200', 'taxonomies found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }++ schema SwaggerSchemaHelpers.paginated('AdminTaxonomy')++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['data']).to be_an(Array)+ expect(data['data'].length).to be >= 1+ end+ end++ response '401', 'unauthorized' do+ let(:'x-spree-api-key') { 'invalid' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ post 'Create a taxonomy' do+ tags 'Taxonomies'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Creates a new taxonomy.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ name: { type: :string, example: 'Categories' },+ position: { type: :integer, example: 1 }+ },+ required: %w[name]+ }++ response '201', 'taxonomy created' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:body) { { name: 'New Taxonomy' } }++ schema '$ref' => '#/components/schemas/AdminTaxonomy'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['name']).to eq('New Taxonomy')+ end+ end++ response '422', 'validation error' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:body) { { name: '' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ path '/api/v3/admin/taxonomies/{id}' do+ get 'Get a taxonomy' do+ tags 'Taxonomies'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a single taxonomy by prefixed ID.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Taxonomy prefixed ID'+ parameter name: :expand, in: :query, type: :string, required: false,+ description: 'Comma-separated associations to expand (e.g., root, taxons)'++ response '200', 'taxonomy found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { taxonomy.prefixed_id }++ schema '$ref' => '#/components/schemas/AdminTaxonomy'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['id']).to eq(taxonomy.prefixed_id)+ end+ end++ response '404', 'taxonomy not found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { 'txmy_nonexistent' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ patch 'Update a taxonomy' do+ tags 'Taxonomies'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Updates a taxonomy. Only provided fields are updated.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Taxonomy prefixed ID'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ name: { type: :string, example: 'Categories' },+ position: { type: :integer, example: 1 }+ }+ }++ response '200', 'taxonomy updated' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { taxonomy.prefixed_id }+ let(:body) { { name: 'Updated Taxonomy' } }++ schema '$ref' => '#/components/schemas/AdminTaxonomy'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['name']).to eq('Updated Taxonomy')+ end+ end++ response '422', 'validation error' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { taxonomy.prefixed_id }+ let(:body) { { name: '' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ delete 'Delete a taxonomy' do+ tags 'Taxonomies'+ security [api_key: [], bearer_auth: []]+ description 'Deletes a taxonomy.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Taxonomy prefixed ID'++ response '204', 'taxonomy deleted' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { taxonomy.prefixed_id }++ run_test!+ end+ end+ end+enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/taxons_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/taxons_spec.rbnew file mode 100644index 0000000000..c0a4c1a095--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/admin/taxons_spec.rb@@ -0,0 +1,286 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Admin Taxons API', type: :request, swagger_doc: 'api-reference/admin.yaml' do+ include_context 'API v3 Admin'++ let!(:taxonomy) { create(:taxonomy, store: store) }+ let!(:taxon) { create(:taxon, taxonomy: taxonomy) }+ let(:Authorization) { "Bearer #{admin_jwt_token}" }++ # ============================================+ # Flat taxon endpoints (index, show only)+ # ============================================++ path '/api/v3/admin/taxons' do+ get 'List taxons' do+ tags 'Taxons'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a flat, paginated list of all taxons for the current store.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'+ parameter name: :'q[name_cont]', in: :query, type: :string, required: false,+ description: 'Filter by name (contains)'++ response '200', 'taxons found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }++ schema SwaggerSchemaHelpers.paginated('AdminTaxon')++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['data']).to be_an(Array)+ 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/admin/taxons/{id}' do+ get 'Get a taxon' do+ tags 'Taxons'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a single taxon by prefixed ID.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Taxon prefixed ID'+ parameter name: :expand, in: :query, type: :string, required: false,+ description: 'Comma-separated associations to expand (e.g., parent, children, ancestors)'++ response '200', 'taxon found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { taxon.prefixed_id }++ schema '$ref' => '#/components/schemas/AdminTaxon'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['id']).to eq(taxon.prefixed_id)+ end+ end++ response '404', 'taxon not found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:id) { 'txn_nonexistent' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ # ============================================+ # Nested taxon endpoints (under taxonomies)+ # ============================================++ path '/api/v3/admin/taxonomies/{taxonomy_id}/taxons' do+ get 'List taxonomy taxons' do+ tags 'Taxons'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a paginated list of taxons belonging to a taxonomy.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :taxonomy_id, in: :path, type: :string, required: true, description: 'Taxonomy prefixed ID'+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'++ response '200', 'taxons found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:taxonomy_id) { taxonomy.prefixed_id }++ schema SwaggerSchemaHelpers.paginated('AdminTaxon')++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['data']).to be_an(Array)+ end+ end+ end++ post 'Create a taxon' do+ tags 'Taxons'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Creates a new taxon within a taxonomy.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :taxonomy_id, in: :path, type: :string, required: true, description: 'Taxonomy prefixed ID'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ name: { type: :string, example: 'T-Shirts' },+ parent_id: { type: :string, description: 'Parent taxon prefixed ID' },+ position: { type: :integer },+ description: { type: :string },+ permalink: { type: :string },+ meta_title: { type: :string },+ meta_description: { type: :string },+ meta_keywords: { type: :string },+ hide_from_nav: { type: :boolean },+ sort_order: { type: :string, example: 'manual' }+ },+ required: %w[name]+ }++ response '201', 'taxon created' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:taxonomy_id) { taxonomy.prefixed_id }+ let(:body) { { name: 'New Taxon', parent_id: taxonomy.root.id } }++ schema '$ref' => '#/components/schemas/AdminTaxon'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['name']).to eq('New Taxon')+ end+ end++ response '422', 'validation error' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:taxonomy_id) { taxonomy.prefixed_id }+ let(:body) { { name: '' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ path '/api/v3/admin/taxonomies/{taxonomy_id}/taxons/{id}' do+ get 'Get a taxonomy taxon' do+ tags 'Taxons'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a single taxon within a taxonomy.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :taxonomy_id, in: :path, type: :string, required: true, description: 'Taxonomy prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Taxon prefixed ID'+ parameter name: :expand, in: :query, type: :string, required: false,+ description: 'Comma-separated associations to expand (e.g., parent, children, ancestors)'++ response '200', 'taxon found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:taxonomy_id) { taxonomy.prefixed_id }+ let(:id) { taxon.prefixed_id }++ schema '$ref' => '#/components/schemas/AdminTaxon'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['id']).to eq(taxon.prefixed_id)+ end+ end++ response '404', 'taxon not found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:taxonomy_id) { taxonomy.prefixed_id }+ let(:id) { 'txn_nonexistent' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ patch 'Update a taxon' do+ tags 'Taxons'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Updates a taxon within a taxonomy. Only provided fields are updated.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :taxonomy_id, in: :path, type: :string, required: true, description: 'Taxonomy prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Taxon prefixed ID'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ name: { type: :string, example: 'T-Shirts' },+ parent_id: { type: :string, description: 'Parent taxon prefixed ID' },+ position: { type: :integer },+ description: { type: :string },+ permalink: { type: :string },+ meta_title: { type: :string },+ meta_description: { type: :string },+ meta_keywords: { type: :string },+ hide_from_nav: { type: :boolean },+ sort_order: { type: :string, example: 'manual' }+ }+ }++ response '200', 'taxon updated' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:taxonomy_id) { taxonomy.prefixed_id }+ let(:id) { taxon.prefixed_id }+ let(:body) { { name: 'Updated Taxon' } }++ schema '$ref' => '#/components/schemas/AdminTaxon'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['name']).to eq('Updated Taxon')+ end+ end++ response '422', 'validation error' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:taxonomy_id) { taxonomy.prefixed_id }+ let(:id) { taxon.prefixed_id }+ let(:body) { { name: '' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ delete 'Delete a taxon' do+ tags 'Taxons'+ security [api_key: [], bearer_auth: []]+ description 'Deletes a taxon from a taxonomy.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :taxonomy_id, in: :path, type: :string, required: true, description: 'Taxonomy prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Taxon prefixed ID'++ response '204', 'taxon deleted' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:taxonomy_id) { taxonomy.prefixed_id }+ let(:id) { taxon.prefixed_id }++ run_test!+ end+ end+ end+enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rbnew file mode 100644index 0000000000..0846474f9f--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rb@@ -0,0 +1,254 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Admin Variants API', type: :request, swagger_doc: 'api-reference/admin.yaml' do+ include_context 'API v3 Admin'++ let!(:product) { create(:product, stores: [store]) }+ let!(:variant) { create(:variant, product: product) }+ let(:Authorization) { "Bearer #{admin_jwt_token}" }++ path '/api/v3/admin/products/{product_id}/variants' do+ get 'List product variants' do+ tags 'Variants'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a paginated list of variants for a product, including the master variant.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'+ parameter name: :expand, in: :query, type: :string, required: false,+ description: 'Comma-separated associations to expand (e.g., images, prices, stock_items)'++ response '200', 'variants found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:product_id) { product.prefixed_id }++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['data']).to be_an(Array)+ end+ end+ end++ post 'Create a variant' do+ tags 'Variants'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description <<~DESC+ Creates a new variant for a product. Supports nested prices and stock items.++ Option types and values are auto-created if they don't exist.+ Prices are upserted by currency. Stock items are upserted by stock location.+ DESC++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ sku: { type: :string, example: 'SKU-001' },+ price: { type: :number, example: 29.99 },+ compare_at_price: { type: :number, example: 39.99 },+ cost_price: { type: :number, example: 10.0 },+ cost_currency: { type: :string, example: 'USD' },+ weight: { type: :number },+ height: { type: :number },+ width: { type: :number },+ depth: { type: :number },+ weight_unit: { type: :string },+ dimensions_unit: { type: :string },+ track_inventory: { type: :boolean },+ tax_category_id: { type: :string },+ option_type: { type: :string, example: 'Size', description: 'Option type name (auto-created if needed)' },+ option_value: { type: :string, example: 'Large', description: 'Option value name (auto-created if needed)' },+ total_on_hand: { type: :integer, example: 100 },+ position: { type: :integer },+ barcode: { type: :string },+ prices: {+ type: :array,+ items: {+ type: :object,+ properties: {+ currency: { type: :string, example: 'USD' },+ amount: { type: :number, example: 29.99 },+ compare_at_amount: { type: :number, example: 39.99 }+ },+ required: %w[currency amount]+ }+ },+ stock_items: {+ type: :array,+ items: {+ type: :object,+ properties: {+ stock_location_id: { type: :string },+ count_on_hand: { type: :integer },+ backorderable: { type: :boolean }+ }+ }+ }+ }+ }++ response '201', 'variant created' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:product_id) { product.prefixed_id }+ let(:body) { { sku: 'NEW-SKU-001', price: 24.99, option_type: 'Size', option_value: 'XL' } }++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['sku']).to eq('NEW-SKU-001')+ end+ end++ response '422', 'validation error' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:product_id) { product.prefixed_id }+ let(:body) { { sku: '' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end+ end++ path '/api/v3/admin/products/{product_id}/variants/{id}' do+ get 'Get a variant' do+ tags 'Variants'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Returns a single variant by prefixed ID.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'+ parameter name: :expand, in: :query, type: :string, required: false,+ description: 'Comma-separated associations to expand (e.g., images, prices, stock_items)'++ response '200', 'variant found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:product_id) { product.prefixed_id }+ let(:id) { variant.prefixed_id }++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['id']).to eq(variant.prefixed_id)+ end+ end++ response '404', 'variant not found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:product_id) { product.prefixed_id }+ let(:id) { 'variant_nonexistent' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ end++ patch 'Update a variant' do+ tags 'Variants'+ consumes 'application/json'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description 'Updates a variant. Only provided fields are updated.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ sku: { type: :string, example: 'SKU-001' },+ price: { type: :number, example: 29.99 },+ compare_at_price: { type: :number, example: 39.99 },+ cost_price: { type: :number, example: 10.0 },+ cost_currency: { type: :string, example: 'USD' },+ weight: { type: :number },+ height: { type: :number },+ width: { type: :number },+ depth: { type: :number },+ weight_unit: { type: :string },+ dimensions_unit: { type: :string },+ track_inventory: { type: :boolean },+ tax_category_id: { type: :string },+ option_type: { type: :string, example: 'Size' },+ option_value: { type: :string, example: 'Large' },+ total_on_hand: { type: :integer, example: 100 },+ position: { type: :integer },+ barcode: { type: :string },+ prices: {+ type: :array,+ items: {+ type: :object,+ properties: {+ currency: { type: :string, example: 'USD' },+ amount: { type: :number, example: 29.99 },+ compare_at_amount: { type: :number, example: 39.99 }+ },+ required: %w[currency amount]+ }+ },+ stock_items: {+ type: :array,+ items: {+ type: :object,+ properties: {+ stock_location_id: { type: :string },+ count_on_hand: { type: :integer },+ backorderable: { type: :boolean }+ }+ }+ }+ }+ }++ response '200', 'variant updated' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:product_id) { product.prefixed_id }+ let(:id) { variant.prefixed_id }+ let(:body) { { sku: 'UPDATED-SKU' } }++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['sku']).to eq('UPDATED-SKU')+ end+ end+ end++ delete 'Delete a variant' do+ tags 'Variants'+ security [api_key: [], bearer_auth: []]+ description 'Soft-deletes a variant.'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product prefixed ID'+ parameter name: :id, in: :path, type: :string, required: true, description: 'Variant prefixed ID'++ response '204', 'variant deleted' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:product_id) { product.prefixed_id }+ let(:id) { variant.prefixed_id }++ run_test!+ end+ end+ end+enddiff --git a/spree/api/spec/swagger_helper.rb b/spree/api/spec/swagger_helper.rbindex 391ce17a9d..01ce1f67a5 100644--- a/spree/api/spec/swagger_helper.rb+++ b/spree/api/spec/swagger_helper.rb@@ -106,6 +106,93 @@ RSpec.configure do |config|},schemas: Spree::Api::OpenAPI::SchemaHelper.all_schemas}+ },++ # Admin API v3 - Administrative API for managing store resources+ 'api-reference/admin.yaml' => {+ openapi: '3.0.3',+ info: {+ title: 'Admin API',+ contact: {+ name: 'Spree Commerce',+ url: 'https://spreecommerce.org',+ email: '[email protected]',+ },+ description: <<~DESC,+ Spree Admin API v3 - Administrative API for managing products, orders, and store settings.++ ## Authentication++ The Admin API requires a secret API key passed in the `x-spree-api-key` header.+ Secret API keys can be generated in the Spree admin dashboard.++ ## Response Format++ All responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.+ Single resource endpoints return a flat JSON object.++ ## Prefixed IDs++ All resources use Stripe-style prefixed IDs (e.g., `prod_86Rf07xd4z`, `variant_k5nR8xLq`).+ These IDs must be used in all API requests.++ ## Error Handling++ Errors return a consistent format:+ ```json+ {+ "error": {+ "code": "validation_error",+ "message": "Validation failed",+ "details": { "name": ["can't be blank"] }+ }+ }+ ```+ DESC+ version: 'v3'+ },+ paths: {},+ servers: [+ {+ url: 'http://{defaultHost}',+ variables: {+ defaultHost: {+ default: 'localhost:3000'+ }+ }+ }+ ],+ tags: [+ { name: 'Products', description: 'Product management' },+ { name: 'Variants', description: 'Product variant management' },+ { name: 'Option Types', description: 'Option type and value management' },+ { name: 'Taxonomies', description: 'Taxonomy management' },+ { name: 'Taxons', description: 'Taxon (category) management' },+ { name: 'Assets', description: 'Product image and asset management' },+ { name: 'Prices', description: 'Variant price management' }+ ],+ 'x-tagGroups': [+ { name: 'Catalog', tags: %w[Products Variants Assets Prices] },+ { name: 'Categories', tags: %w[Taxonomies Taxons] },+ { name: 'Options', tags: ['Option Types'] }+ ],+ components: {+ securitySchemes: {+ api_key: {+ type: :apiKey,+ name: 'x-spree-api-key',+ in: :header,+ description: 'Secret API key for admin access'+ },+ bearer_auth: {+ type: :http,+ scheme: :bearer,+ bearerFormat: 'JWT',+ description: 'JWT token for admin user authentication'+ }+ },+ schemas: Spree::Api::OpenAPI::SchemaHelper.admin_schemas+ }}}