spree_api 6.0.2 → 6.0.3

data/openapi/admin.yaml

@@ -3916,6 +3916,7 @@ paths:
       summary: Reposition a category product
       tags:
       - Categories
+      operationId: categories_reposition_product
       security:
       - api_key: []
         bearer_auth: []
@@ -6081,6 +6082,9 @@ paths:
                 "$ref": "#/components/schemas/ErrorResponse"
   "/api/v3/admin/customers/{id}/anonymize":
     post:
+      x-spree-agent: false
+      x-spree-agent-reason: Irreversible erasure of a person's data under GDPR Art.
+        17, which is not something to offer a model behind one confirmation prompt.
       summary: Erase a customer's personal data
       tags:
       - Customers
@@ -7701,6 +7705,94 @@ paths:
             schema:
               "$ref": "#/components/schemas/TaxIdentifierUpdateParams"
         required: true
+  "/api/v3/admin/customers/{customer_id}/tax_identifiers/{id}/validate":
+    parameters:
+    - name: x-spree-api-key
+      in: header
+      required: true
+      schema:
+        type: string
+    - name: Authorization
+      in: header
+      required: true
+      schema:
+        type: string
+    - name: customer_id
+      in: path
+      required: true
+      schema:
+        type: string
+    - name: id
+      in: path
+      required: true
+      schema:
+        type: string
+    post:
+      summary: Re-check a customer tax registration
+      tags:
+      - Customers
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const registration = await client.customers.taxIdentifiers.validate(
+            'cust_UkLWZg9DAJ',
+            'txi_UkLWZg9DAJ',
+          )
+      - lang: bash
+        label: Spree CLI
+        source: spree api post /customers/{customer_id}/tax_identifiers/{id}/validate
+          -d '{ ... }'
+      operationId: customer_tax_identifiers_validate
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Asks the registry again. Manual because a registry answers only "valid now" — a number verified
+        last year may have been deregistered since — and because a check that came back unavailable
+        cannot otherwise be retried without editing the number.
+
+
+        **Required scope:** `write_customers` (for API-key authentication).
+      responses:
+        '202':
+          description: registry check queued
+          content:
+            application/json:
+              example:
+                id: txi_UkLWZg9DAJ
+                kind: eu_vat
+                value: DE100000032
+                validation_status: pending
+                validation_evidence:
+                source:
+                validated_at:
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+                validatable: true
+                customer_id: cust_UkLWZg9DAJ
+                cart_id:
+                order_id:
+              schema:
+                "$ref": "#/components/schemas/TaxIdentifier"
+        '422':
+          description: no validator installed for this kind
+          content:
+            application/json:
+              example:
+                error:
+                  code: tax_id_not_validatable
+                  message: No registry validator is installed for tax identifier kind
+                    'eu_vat'
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
   "/api/v3/admin/customers":
     get:
       summary: List customers
@@ -15999,6 +16091,81 @@ paths:
             schema:
               "$ref": "#/components/schemas/ClaimUpdateParams"
         required: true
+  "/api/v3/admin/orders/{order_id}/claims/{id}/approve":
+    patch:
+      summary: Approve a claim
+      tags:
+      - Orders
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const claim = await client.orders.claims.approve('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ')
+      - lang: bash
+        label: Spree CLI
+        source: spree api patch /orders/{order_id}/claims/{id}/approve -d '{ ... }'
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Accepts an open claim, the step before resolving it with a refund, a replacement or both. Only an open claim can be approved; deny it to turn it down.
+
+        **Required scope:** `write_orders` (for API-key authentication).
+      parameters:
+      - name: x-spree-api-key
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: Authorization
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: order_id
+        in: path
+        required: true
+        description: Order prefixed ID
+        schema:
+          type: string
+      - name: id
+        in: path
+        required: true
+        description: Claim prefixed ID
+        schema:
+          type: string
+      responses:
+        '200':
+          description: claim approved
+          content:
+            application/json:
+              example:
+                id: claim_UkLWZg9DAJ
+                number: CLM1001
+                status: approved
+                resolution:
+                order_id: or_UkLWZg9DAJ
+                reason_id:
+                refund_total: '10.00'
+                approved_at: '2026-01-15T12:00:00Z'
+                resolved_at:
+                denied_at:
+                canceled_at:
+                memo: Arrived with a cracked screen
+                metadata: {}
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+                created_by_id: adm_UkLWZg9DAJ
+                created_by_type: admin_user
+              schema:
+                "$ref": "#/components/schemas/Claim"
   "/api/v3/admin/orders/{order_id}/claims/{id}/resolve":
     patch:
       summary: Resolve a claim
@@ -16510,6 +16677,149 @@ paths:
                 required:
                 - data
                 - meta
+  "/api/v3/admin/digital_links/{id}":
+    parameters:
+    - name: id
+      in: path
+      required: true
+      description: Digital link ID
+      schema:
+        type: string
+    get:
+      summary: Get a digital link
+      tags:
+      - Orders
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Returns a single download link with its download count and expiry.
+
+        **Required scope:** `read_orders` (for API-key authentication).
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const digitalLink = await client.digitalLinks.retrieve('dl_xxx')
+      - lang: bash
+        label: Spree CLI
+        source: spree api get /digital_links/{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
+      responses:
+        '200':
+          description: digital link found
+          content:
+            application/json:
+              example:
+                id: dl_UkLWZg9DAJ
+                access_counter: 0
+                filename: thinking-cat.jpg
+                content_type: image/jpeg
+                download_url: "/api/v3/store/digital_links/ks9F16gjTLQPCzwFDpj2ifrJ"
+                expires_at: '2026-01-22T12:00:00Z'
+                authorizable: true
+                expired: false
+                access_limit_exceeded: false
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+              schema:
+                "$ref": "#/components/schemas/DigitalLink"
+        '404':
+          description: digital link not found
+          content:
+            application/json:
+              example:
+                error:
+                  code: record_not_found
+                  message: Digital link not found
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+  "/api/v3/admin/digital_links/{id}/reset":
+    parameters:
+    - name: id
+      in: path
+      required: true
+      description: Digital link ID
+      schema:
+        type: string
+    patch:
+      summary: Reset a digital link
+      tags:
+      - Orders
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const digitalLink = await client.digitalLinks.reset('dl_xxx')
+      - lang: bash
+        label: Spree CLI
+        source: spree api patch /digital_links/{id}/reset -d '{ ... }'
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Gives the customer their full download allowance back and restarts the
+        link's expiry clock. Use it when a download failed, or the file was
+        replaced after the customer had used up their attempts.
+
+
+        **Required scope:** `write_orders` (for API-key authentication).
+      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:
+        '200':
+          description: digital link reset
+          content:
+            application/json:
+              example:
+                id: dl_UkLWZg9DAJ
+                access_counter: 0
+                filename: thinking-cat.jpg
+                content_type: image/jpeg
+                download_url: "/api/v3/store/digital_links/tPqch4JvZidezkNn2YoqxDLc"
+                expires_at: '2026-01-22T12:00:00Z'
+                authorizable: true
+                expired: false
+                access_limit_exceeded: false
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+              schema:
+                "$ref": "#/components/schemas/DigitalLink"
   "/api/v3/admin/exchanges":
     get:
       summary: List exchanges
@@ -16999,6 +17309,92 @@ paths:
             schema:
               "$ref": "#/components/schemas/ExchangeUpdateParams"
         required: true
+  "/api/v3/admin/orders/{order_id}/exchanges/{id}/approve":
+    patch:
+      summary: Approve an exchange
+      tags:
+      - Orders
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const exchange = await client.orders.exchanges.approve('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ')
+      - lang: bash
+        label: Spree CLI
+        source: spree api patch /orders/{order_id}/exchanges/{id}/approve -d '{ ...
+          }'
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Accepts a requested exchange so the customer can send the goods back for their replacement. Only a requested exchange can be approved; receive it once the goods arrive.
+
+        **Required scope:** `write_orders` (for API-key authentication).
+      parameters:
+      - name: x-spree-api-key
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: Authorization
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: order_id
+        in: path
+        required: true
+        description: Order prefixed ID
+        schema:
+          type: string
+      - name: id
+        in: path
+        required: true
+        description: Exchange prefixed ID
+        schema:
+          type: string
+      responses:
+        '200':
+          description: exchange approved
+          content:
+            application/json:
+              example:
+                id: exch_UkLWZg9DAJ
+                number: EX1001
+                status: approved
+                order_id: or_UkLWZg9DAJ
+                reason_id:
+                price_difference: '9.99'
+                approved_at: '2026-01-15T12:00:00Z'
+                received_at:
+                fulfilled_at:
+                canceled_at:
+                memo: Wrong size
+                metadata: {}
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+                stock_location_id: sloc_UkLWZg9DAJ
+                created_by_id: adm_UkLWZg9DAJ
+                created_by_type: admin_user
+              schema:
+                "$ref": "#/components/schemas/Exchange"
+        '422':
+          description: the exchange is not requested
+          content:
+            application/json:
+              example:
+                error:
+                  code: processing_error
+                  message: Not requested
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
   "/api/v3/admin/orders/{order_id}/exchanges/{id}/receive":
     patch:
       summary: Receive an exchange
@@ -20613,6 +21009,147 @@ paths:
                 cancel_reason_name:
                 customer_id: cust_UkLWZg9DAJ
                 freight_summary:
+  "/api/v3/admin/orders/{id}/resend_digital_links":
+    post:
+      summary: Resend digital download links
+      tags:
+      - Orders
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          await client.orders.resendDigitalLinks('or_UkLWZg9DAJ')
+      - lang: bash
+        label: Spree CLI
+        source: spree api post /orders/{id}/resend_digital_links -d '{ ... }'
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Emails the customer their download links for the digital products on
+        this order again. Nothing is sent when the order has no digital links or
+        the store does not send transactional emails. Use it when the original
+        email was lost; to restore used-up downloads or an expired link, reset
+        the digital link instead.
+
+
+        **Required scope:** `write_orders` (for API-key authentication).
+      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: Order ID
+        schema:
+          type: string
+      responses:
+        '200':
+          description: digital links resent
+          content:
+            application/json:
+              example:
+                id: or_UkLWZg9DAJ
+                market_id: mkt_UkLWZg9DAJ
+                withdrawal_period_ends_at:
+                within_withdrawal_period: true
+                shipping_eq_billing_address: false
+                cart_id:
+                channel_id: ch_UkLWZg9DAJ
+                company_id:
+                company_name:
+                po_document_filename:
+                po_document_byte_size:
+                number: R1001
+                email: ivana@schmidtfeest.com
+                customer_note:
+                po_number:
+                currency: USD
+                locale: en
+                total_quantity: 1
+                coupon_code:
+                fulfillment_status:
+                payment_status:
+                completed_at: '2026-01-15T12:00:00.000Z'
+                item_total: '10.00'
+                discount_total: '0.00'
+                tax_total: '0.00'
+                included_tax_total: '0.00'
+                additional_tax_total: '0.00'
+                delivery_total: '100.00'
+                fee_total: '0.00'
+                gift_card_total: '0.00'
+                store_credit_total: '0.00'
+                total: '110.00'
+                amount_due: '110.00'
+                covered_by_store_credit: false
+                adjustment_total: '0.00'
+                gift_card:
+                market:
+                  id: mkt_UkLWZg9DAJ
+                  name: United States
+                  currency: USD
+                  default_locale: en
+                  tax_inclusive: false
+                  default: true
+                  country_codes:
+                  - US
+                  supported_locales:
+                  - en
+                  created_at: '2026-11-03T16:44:09.130Z'
+                  updated_at: '2026-11-03T16:44:09.130Z'
+                  tax_provider:
+                external_references: {}
+                status: placed
+                last_ip_address:
+                considered_risky: false
+                confirmation_delivered: false
+                store_owner_notification_delivered:
+                metadata: {}
+                cancel_note:
+                canceled_at:
+                approved_at:
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+                payment_total: '0.00'
+                commission_amount_total: '0.00'
+                commission_tax_total: '0.00'
+                commission_total: '0.00'
+                preferred_stock_location_id:
+                po_document_url:
+                seller_id:
+                order_group_id:
+                tags: []
+                internal_note:
+                internal_note_html:
+                approver_id:
+                approver_type:
+                canceler_id:
+                canceler_type:
+                created_by_id:
+                created_by_type:
+                cancel_reason_id:
+                cancel_reason_name:
+                customer_id: cust_UkLWZg9DAJ
+                freight_summary:
+              schema:
+                "$ref": "#/components/schemas/Order"
   "/api/v3/admin/returns":
     get:
       summary: List returns
@@ -21138,18 +21675,11 @@ paths:
             schema:
               "$ref": "#/components/schemas/ReturnUpdateParams"
         required: true
-  "/api/v3/admin/orders/{order_id}/returns/{id}/receive":
+  "/api/v3/admin/orders/{order_id}/returns/{id}/approve":
     patch:
-      summary: Receive a return
+      summary: Approve a return
       tags:
       - Orders
-      security:
-      - api_key: []
-        bearer_auth: []
-      description: |-
-        Records what arrived on an approved return. Omit `items` to receive everything as requested and resellable; send rows for a partial or damaged receipt.
-
-        **Required scope:** `write_orders` (for API-key authentication).
       x-codeSamples:
       - lang: javascript
         label: Spree Admin SDK
@@ -21161,13 +21691,18 @@ paths:
             secretKey: 'sk_xxx',
           })
 
-          // Omit `items` to receive everything as requested and resellable.
-          const orderReturn = await client.orders.returns.receive('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
-            items: [{ return_line_item_id: 'rli_UkLWZg9DAJ', quantity: 1, resellable: false }],
-          })
+          const orderReturn = await client.orders.returns.approve('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ')
       - lang: bash
         label: Spree CLI
-        source: spree api patch /orders/{order_id}/returns/{id}/receive -d '{"items":[{"return_line_item_id":"rli_UkLWZg9DAJ","quantity":1,"resellable":false}]}'
+        source: spree api patch /orders/{order_id}/returns/{id}/approve -d '{ ...
+          }'
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Accepts a requested return so the customer can send the goods back. Only a requested return can be approved; receive it once the goods arrive.
+
+        **Required scope:** `write_orders` (for API-key authentication).
       parameters:
       - name: x-spree-api-key
         in: header
@@ -21193,19 +21728,19 @@ paths:
           type: string
       responses:
         '200':
-          description: return received
+          description: return approved
           content:
             application/json:
               example:
                 id: ret_UkLWZg9DAJ
                 number: RET1001
-                status: received
+                status: approved
                 order_id: or_UkLWZg9DAJ
                 reason_id:
                 refund_total: '10.00'
                 refund_tax_total: '0.00'
                 approved_at: '2026-01-15T12:00:00Z'
-                received_at: '2026-01-15T12:00:00Z'
+                received_at:
                 refunded_at:
                 canceled_at:
                 external_references: {}
@@ -21214,8 +21749,8 @@ paths:
                 created_at: '2026-01-15T12:00:00.000Z'
                 updated_at: '2026-01-15T12:00:00.000Z'
                 stock_location_id: sloc_UkLWZg9DAJ
-                created_by_id:
-                created_by_type:
+                created_by_id: adm_UkLWZg9DAJ
+                created_by_type: admin_user
                 refunded_total: '0.00'
                 refundable_total: '10.00'
                 documents: []
@@ -21223,23 +21758,28 @@ paths:
                 deliveries: []
               schema:
                 "$ref": "#/components/schemas/Return"
-      requestBody:
-        content:
-          application/json:
-            schema:
-              "$ref": "#/components/schemas/ReturnReceiveParams"
-  "/api/v3/admin/orders/{order_id}/returns/{id}/refund":
+        '422':
+          description: the return is not requested
+          content:
+            application/json:
+              example:
+                error:
+                  code: processing_error
+                  message: Not requested
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+  "/api/v3/admin/orders/{order_id}/returns/{id}/receive":
     patch:
-      summary: Refund a return
+      summary: Receive a return
       tags:
       - Orders
       security:
       - api_key: []
         bearer_auth: []
       description: |-
-        Pays the customer back for a received return, to store credit or through the original payment.
+        Records what arrived on an approved return. Omit `items` to receive everything as requested and resellable; send rows for a partial or damaged receipt.
 
-        **Required scope:** `write_orders` and `write_refunds` (for API-key authentication).
+        **Required scope:** `write_orders` (for API-key authentication).
       x-codeSamples:
       - lang: javascript
         label: Spree Admin SDK
@@ -21251,13 +21791,103 @@ paths:
             secretKey: 'sk_xxx',
           })
 
-          const orderReturn = await client.orders.returns.refund('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
-            amount: '29.99',
-            refund_method: 'original_payment',
+          // Omit `items` to receive everything as requested and resellable.
+          const orderReturn = await client.orders.returns.receive('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
+            items: [{ return_line_item_id: 'rli_UkLWZg9DAJ', quantity: 1, resellable: false }],
           })
       - lang: bash
         label: Spree CLI
-        source: spree api patch /orders/{order_id}/returns/{id}/refund -d '{"amount":"29.99","refund_method":"original_payment"}'
+        source: spree api patch /orders/{order_id}/returns/{id}/receive -d '{"items":[{"return_line_item_id":"rli_UkLWZg9DAJ","quantity":1,"resellable":false}]}'
+      parameters:
+      - name: x-spree-api-key
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: Authorization
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: order_id
+        in: path
+        required: true
+        description: Order prefixed ID
+        schema:
+          type: string
+      - name: id
+        in: path
+        required: true
+        description: Return prefixed ID
+        schema:
+          type: string
+      responses:
+        '200':
+          description: return received
+          content:
+            application/json:
+              example:
+                id: ret_UkLWZg9DAJ
+                number: RET1001
+                status: received
+                order_id: or_UkLWZg9DAJ
+                reason_id:
+                refund_total: '10.00'
+                refund_tax_total: '0.00'
+                approved_at: '2026-01-15T12:00:00Z'
+                received_at: '2026-01-15T12:00:00Z'
+                refunded_at:
+                canceled_at:
+                external_references: {}
+                memo: Item did not fit
+                metadata: {}
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+                stock_location_id: sloc_UkLWZg9DAJ
+                created_by_id:
+                created_by_type:
+                refunded_total: '0.00'
+                refundable_total: '10.00'
+                documents: []
+                labels: []
+                deliveries: []
+              schema:
+                "$ref": "#/components/schemas/Return"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              "$ref": "#/components/schemas/ReturnReceiveParams"
+  "/api/v3/admin/orders/{order_id}/returns/{id}/refund":
+    patch:
+      summary: Refund a return
+      tags:
+      - Orders
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Pays the customer back for a received return, to store credit or through the original payment.
+
+        **Required scope:** `write_orders` and `write_refunds` (for API-key authentication).
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const orderReturn = await client.orders.returns.refund('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ', {
+            amount: '29.99',
+            refund_method: 'original_payment',
+          })
+      - lang: bash
+        label: Spree CLI
+        source: spree api patch /orders/{order_id}/returns/{id}/refund -d '{"amount":"29.99","refund_method":"original_payment"}'
       parameters:
       - name: x-spree-api-key
         in: header
@@ -21558,6 +22188,107 @@ paths:
                 required:
                 - data
                 - meta
+  "/api/v3/admin/orders/{order_id}/returns/{return_id}/labels/{id}/refund":
+    patch:
+      summary: Refund a return label
+      tags:
+      - Orders
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const label = await client.orders.returns.labels.refund(
+            'or_UkLWZg9DAJ',
+            'ret_UkLWZg9DAJ',
+            'lbl_UkLWZg9DAJ',
+          )
+      - lang: bash
+        label: Spree CLI
+        source: spree api patch /orders/{order_id}/returns/{return_id}/labels/{id}/refund
+          -d '{ ... }'
+      operationId: return_labels_refund
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Asks the carrier to refund a purchased return label the customer never used, such as when the return is canceled. An uploaded label has nothing to refund.
+
+        **Required scope:** `write_orders` (for API-key authentication).
+      parameters:
+      - name: x-spree-api-key
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: Authorization
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: order_id
+        in: path
+        required: true
+        description: Order prefixed ID
+        schema:
+          type: string
+      - name: return_id
+        in: path
+        required: true
+        description: Return prefixed ID
+        schema:
+          type: string
+      - name: id
+        in: path
+        required: true
+        description: Shipping label prefixed ID
+        schema:
+          type: string
+      responses:
+        '200':
+          description: refund filed
+          content:
+            application/json:
+              example:
+                id: lbl_UkLWZg9DAJ
+                source: purchased
+                status: refunded
+                carrier: ups
+                carrier_name: UPS
+                service: Ground
+                tracking_number: 1Z879E930346830007
+                currency: USD
+                format: pdf
+                external_id: shp_4
+                metadata: {}
+                refunded_at: '2026-01-15T12:00:00.000Z'
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+                owner_id: ret_UkLWZg9DAJ
+                owner_type: return
+                cost: '7.25'
+                integration_id:
+                file_pending: false
+                download_url:
+              schema:
+                "$ref": "#/components/schemas/ShippingLabel"
+        '422':
+          description: uploaded labels cannot be refunded
+          content:
+            application/json:
+              example:
+                error:
+                  code: processing_error
+                  message: An uploaded label was not bought through Spree and cannot
+                    be refunded — delete it instead
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
   "/api/v3/admin/payment_methods/{payment_method_id}/custom_fields":
     get:
       summary: List payment method custom fields
@@ -22319,6 +23050,8 @@ paths:
                   updated_at: '2026-01-15T12:00:00.000Z'
                   avs_risky: false
                   cvv_risky: false
+                  can_void: true
+                  can_capture: false
                   captured_amount: '0.00'
                   order_id: or_UkLWZg9DAJ
                 meta:
@@ -22403,6 +23136,8 @@ paths:
                 updated_at: '2026-01-15T12:00:00.000Z'
                 avs_risky: false
                 cvv_risky: false
+                can_void: true
+                can_capture: true
                 captured_amount: '0.00'
                 order_id: or_gbHJdmfrXB
       requestBody:
@@ -22513,6 +23248,8 @@ paths:
                 updated_at: '2026-01-15T12:00:00.000Z'
                 avs_risky: false
                 cvv_risky: false
+                can_void: true
+                can_capture: false
                 captured_amount: '0.00'
                 order_id: or_UkLWZg9DAJ
   "/api/v3/admin/orders/{order_id}/payments/{id}/capture":
@@ -22604,6 +23341,8 @@ paths:
                 updated_at: '2026-01-15T12:00:00.000Z'
                 avs_risky: false
                 cvv_risky: false
+                can_void: true
+                can_capture: false
                 captured_amount: '110.00'
                 order_id: or_UkLWZg9DAJ
         '422':
@@ -22709,6 +23448,8 @@ paths:
                 updated_at: '2026-01-15T12:00:00.000Z'
                 avs_risky: false
                 cvv_risky: false
+                can_void: false
+                can_capture: false
                 captured_amount: '0.00'
                 order_id: or_UkLWZg9DAJ
   "/api/v3/admin/price_lists":
@@ -23855,6 +24596,9 @@ paths:
         required: true
   "/api/v3/admin/prices/bulk_destroy":
     delete:
+      x-spree-agent: false
+      x-spree-agent-reason: Deletes many prices in one call behind a single confirmation;
+        delete_resource removes them one at a time.
       summary: Bulk-delete prices
       tags:
       - Pricing
@@ -24993,6 +25737,7 @@ paths:
                   seller_name:
                   product_type_id:
                   tax_category_id: taxcat_UkLWZg9DAJ
+                  total_on_hand: 0
                 meta:
                   page: 1
                   limit: 25
@@ -25136,6 +25881,7 @@ paths:
                 seller_name:
                 product_type_id:
                 tax_category_id:
+                total_on_hand: 0
               schema:
                 "$ref": "#/components/schemas/Product"
         '422':
@@ -25270,6 +26016,7 @@ paths:
                 seller_name:
                 product_type_id:
                 tax_category_id: taxcat_UkLWZg9DAJ
+                total_on_hand: 0
               schema:
                 "$ref": "#/components/schemas/Product"
         '404':
@@ -25390,6 +26137,7 @@ paths:
                 seller_name:
                 product_type_id:
                 tax_category_id: taxcat_UkLWZg9DAJ
+                total_on_hand: 0
               schema:
                 "$ref": "#/components/schemas/Product"
         '422':
@@ -25475,8 +26223,126 @@ paths:
                       specific: false
               schema:
                 "$ref": "#/components/schemas/ErrorResponse"
+  "/api/v3/admin/products/{id}/clone":
+    parameters:
+    - name: id
+      in: path
+      required: true
+      description: Product ID
+      schema:
+        type: string
+    post:
+      summary: Clone a product
+      tags:
+      - Products
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const copy = await client.products.clone('prod_UkLWZg9DAJ')
+      - lang: bash
+        label: Spree CLI
+        source: spree api post /products/{id}/clone -d '{ ... }'
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Creates a draft copy of a product, named "COPY OF …", with its variants,
+        prices, stock locations, images, categories, channels and tags; stock on
+        hand starts at zero. Use it to start a similar product from an existing
+        one instead of building it from scratch.
+
+
+        **Required scope:** `write_products` (for API-key authentication).
+      parameters:
+      - name: x-spree-api-key
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: Authorization
+        in: header
+        required: true
+        schema:
+          type: string
+      responses:
+        '201':
+          description: product cloned
+          content:
+            application/json:
+              example:
+                id: prod_gbHJdmfrXB
+                name: COPY OF Product 1462357
+                slug: copy-of-product-1462357
+                meta_title:
+                meta_description:
+                meta_keywords:
+                variant_count: 1
+                available_on:
+                preorder_ships_at:
+                purchasable: true
+                preorder: false
+                in_stock: false
+                backorderable: true
+                available: false
+                description: Dolore facere hic laboriosam sapiente nobis. Doloribus
+                  deleniti quasi esse aliquid voluptatem. Rem voluptate omnis suscipit
+                  adipisci laudantium. Deleniti error dolorum ratione dolor assumenda
+                  iusto. Laborum non rem sapiente temporibus quam inventore. Voluptatum
+                  magnam hic molestias laudantium necessitatibus. Totam ducimus provident
+                  aliquam repellendus nam maxime error natus. Ex aspernatur nostrum
+                  deserunt maxime quis occaecati expedita dolore. Debitis est laboriosam
+                  modi aspernatur cumque. Sapiente ab corrupti quos doloremque eius.
+                  Laborum officiis culpa voluptate fuga sed. Nemo possimus vel architecto
+                  quo modi. Velit aut non iusto exercitationem nostrum nemo. Velit
+                  illo nisi quaerat perspiciatis facilis temporibus quae esse.
+                description_html: |-
+                  Dolore facere hic laboriosam sapiente nobis. Doloribus deleniti quasi esse aliquid voluptatem. Rem voluptate omnis suscipit adipisci laudantium.
+                  Deleniti error dolorum ratione dolor assumenda iusto. Laborum non rem sapiente temporibus quam inventore. Voluptatum magnam hic molestias laudantium necessitatibus. Totam ducimus provident aliquam repellendus nam maxime error natus.
+                  Ex aspernatur nostrum deserunt maxime quis occaecati expedita dolore. Debitis est laboriosam modi aspernatur cumque. Sapiente ab corrupti quos doloremque eius.
+                  Laborum officiis culpa voluptate fuga sed. Nemo possimus vel architecto quo modi. Velit aut non iusto exercitationem nostrum nemo. Velit illo nisi quaerat perspiciatis facilis temporibus quae esse.
+                default_variant_id: variant_gbHJdmfrXB
+                buy_box_variant_id: variant_gbHJdmfrXB
+                thumbnail_url:
+                tags: []
+                price:
+                  id: price_gbHJdmfrXB
+                  currency: USD
+                  amount: '19.99'
+                  compare_at_amount:
+                  price_list_id:
+                  min_quantity: 1
+                  variant_id: variant_gbHJdmfrXB
+                  created_at: '2026-01-15T12:00:00.000Z'
+                  updated_at: '2026-01-15T12:00:00.000Z'
+                original_price:
+                seller_id:
+                external_references: {}
+                status: draft
+                metadata: {}
+                deleted_at:
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+                delivery_profile_id: fp_UkLWZg9DAJ
+                seller_name:
+                product_type_id:
+                tax_category_id: taxcat_UkLWZg9DAJ
+                total_on_hand: 0
+              schema:
+                "$ref": "#/components/schemas/Product"
   "/api/v3/admin/products/bulk_status_update":
     post:
+      x-spree-agent: false
+      x-spree-agent-reason: Writes the status column for many products at once, skipping
+        the status workflows and their events; products_activate, products_archive and
+        products_draft run them.
       summary: Bulk-update product status
       tags:
       - Products
@@ -26036,6 +26902,9 @@ paths:
         required: true
   "/api/v3/admin/products/bulk_destroy":
     delete:
+      x-spree-agent: false
+      x-spree-agent-reason: Deletes many products in one call behind a single confirmation;
+        delete_resource removes them one at a time.
       summary: Bulk-delete products
       tags:
       - Products
@@ -26126,7 +26995,6 @@ paths:
         Puts a product a seller submitted for review on sale, and closes the
         submission. Only a product awaiting review can be approved.
 
-
         **Required scope:** `write_products` (for API-key authentication).
       parameters:
       - name: x-spree-api-key
@@ -26198,6 +27066,7 @@ paths:
                 seller_name:
                 product_type_id:
                 tax_category_id: taxcat_UkLWZg9DAJ
+                total_on_hand: 0
               schema:
                 "$ref": "#/components/schemas/Product"
         '422':
@@ -26325,6 +27194,7 @@ paths:
                 seller_name:
                 product_type_id:
                 tax_category_id: taxcat_UkLWZg9DAJ
+                total_on_hand: 0
               schema:
                 "$ref": "#/components/schemas/Product"
       requestBody:
@@ -26333,6 +27203,383 @@ paths:
             schema:
               "$ref": "#/components/schemas/ProductRejectParams"
         required: true
+  "/api/v3/admin/products/{id}/activate":
+    parameters:
+    - name: id
+      in: path
+      required: true
+      description: Product ID
+      schema:
+        type: string
+    patch:
+      summary: Activate a product
+      tags:
+      - Products
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const product = await client.products.activate('prod_UkLWZg9DAJ')
+      - lang: bash
+        label: Spree CLI
+        source: spree api patch /products/{id}/activate -d '{ ... }'
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Puts one product on sale. Runs the activation workflow, so its hooks and the `product.activated` event fire, which `bulk_status_update` does not. A product awaiting review is refused: approve or reject it instead.
+
+
+        **Required scope:** `write_products` (for API-key authentication).
+      parameters:
+      - name: x-spree-api-key
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: Authorization
+        in: header
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: product active
+          content:
+            application/json:
+              example:
+                id: prod_gbHJdmfrXB
+                name: Product 1604119
+                slug: product-1604119
+                meta_title:
+                meta_description:
+                meta_keywords:
+                variant_count: 1
+                available_on:
+                preorder_ships_at:
+                purchasable: true
+                preorder: false
+                in_stock: false
+                backorderable: true
+                available: true
+                description: Tempora doloribus sit consectetur cumque omnis. Quod
+                  fugit dicta ullam omnis. Hic dolorem asperiores nemo est sed nihil
+                  quia deleniti. Saepe aperiam eos nulla quia porro minima officiis
+                  cum. Eius dignissimos laudantium sequi incidunt. Sed nihil voluptate
+                  aliquid nisi. Veritatis tenetur quos aspernatur modi perspiciatis
+                  quaerat. Voluptas harum neque labore fuga reprehenderit unde quasi.
+                  Omnis quam autem in ipsam aspernatur architecto alias recusandae.
+                  Repudiandae ratione vel expedita corporis et pariatur rem sapiente.
+                  Velit laboriosam nulla quibusdam fugit minus itaque ut repellat.
+                  Incidunt est fugiat totam ipsa quod deserunt. Natus sequi numquam
+                  laudantium non similique saepe ipsam quos. Ad impedit necessitatibus
+                  quo nesciunt blanditiis id similique recusandae. Ut occaecati debitis
+                  aliquam accusantium sed distinctio neque. Labore quos quam optio
+                  aperiam dolores aspernatur vitae odio. Eius nam adipisci corrupti
+                  incidunt quod sapiente tempora dicta.
+                description_html: |-
+                  Tempora doloribus sit consectetur cumque omnis. Quod fugit dicta ullam omnis. Hic dolorem asperiores nemo est sed nihil quia deleniti.
+                  Saepe aperiam eos nulla quia porro minima officiis cum. Eius dignissimos laudantium sequi incidunt. Sed nihil voluptate aliquid nisi.
+                  Veritatis tenetur quos aspernatur modi perspiciatis quaerat. Voluptas harum neque labore fuga reprehenderit unde quasi. Omnis quam autem in ipsam aspernatur architecto alias recusandae. Repudiandae ratione vel expedita corporis et pariatur rem sapiente.
+                  Velit laboriosam nulla quibusdam fugit minus itaque ut repellat. Incidunt est fugiat totam ipsa quod deserunt. Natus sequi numquam laudantium non similique saepe ipsam quos. Ad impedit necessitatibus quo nesciunt blanditiis id similique recusandae.
+                  Ut occaecati debitis aliquam accusantium sed distinctio neque. Labore quos quam optio aperiam dolores aspernatur vitae odio. Eius nam adipisci corrupti incidunt quod sapiente tempora dicta.
+                default_variant_id: variant_gbHJdmfrXB
+                buy_box_variant_id: variant_gbHJdmfrXB
+                thumbnail_url:
+                tags: []
+                price:
+                  id: price_gbHJdmfrXB
+                  currency: USD
+                  amount: '19.99'
+                  compare_at_amount:
+                  price_list_id:
+                  min_quantity: 1
+                  variant_id: variant_gbHJdmfrXB
+                  created_at: '2026-01-15T12:00:00.000Z'
+                  updated_at: '2026-01-15T12:00:00.000Z'
+                original_price:
+                seller_id:
+                external_references: {}
+                status: active
+                metadata: {}
+                deleted_at:
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+                delivery_profile_id: fp_UkLWZg9DAJ
+                seller_name:
+                product_type_id:
+                tax_category_id: taxcat_UkLWZg9DAJ
+                total_on_hand: 0
+              schema:
+                "$ref": "#/components/schemas/Product"
+        '422':
+          description: the product is awaiting review
+          content:
+            application/json:
+              example:
+                error:
+                  code: product_in_review
+                  message: A product awaiting review is approved or rejected, not
+                    moved to another status
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+  "/api/v3/admin/products/{id}/archive":
+    parameters:
+    - name: id
+      in: path
+      required: true
+      description: Product ID
+      schema:
+        type: string
+    patch:
+      summary: Archive a product
+      tags:
+      - Products
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const product = await client.products.archive('prod_UkLWZg9DAJ')
+      - lang: bash
+        label: Spree CLI
+        source: spree api patch /products/{id}/archive -d '{ ... }'
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Takes one product off sale and archives it; activating it puts it back on sale. Runs the archive workflow, so its hooks and its event fire. A product awaiting review is refused: approve or reject it instead.
+
+
+        **Required scope:** `write_products` (for API-key authentication).
+      parameters:
+      - name: x-spree-api-key
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: Authorization
+        in: header
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: product archived
+          content:
+            application/json:
+              example:
+                id: prod_gbHJdmfrXB
+                name: Product 1644768
+                slug: product-1644768
+                meta_title:
+                meta_description:
+                meta_keywords:
+                variant_count: 1
+                available_on:
+                preorder_ships_at:
+                purchasable: true
+                preorder: false
+                in_stock: false
+                backorderable: true
+                available: false
+                description: In exercitationem nobis illo accusamus non quibusdam.
+                  Minus corporis commodi magni maxime cumque beatae. Exercitationem
+                  provident tempore est corrupti eius at dolor. Rerum delectus id
+                  aspernatur consequuntur quod enim. Quis omnis amet inventore alias
+                  minima praesentium. Quaerat reprehenderit deleniti atque inventore.
+                  Nemo quas nam qui architecto eligendi vel pariatur. Veritatis accusantium
+                  molestias deleniti omnis autem modi. Officiis optio quidem iste
+                  nihil delectus commodi. Aperiam amet omnis eum praesentium natus
+                  recusandae suscipit.
+                description_html: |-
+                  In exercitationem nobis illo accusamus non quibusdam. Minus corporis commodi magni maxime cumque beatae. Exercitationem provident tempore est corrupti eius at dolor. Rerum delectus id aspernatur consequuntur quod enim.
+                  Quis omnis amet inventore alias minima praesentium. Quaerat reprehenderit deleniti atque inventore. Nemo quas nam qui architecto eligendi vel pariatur.
+                  Veritatis accusantium molestias deleniti omnis autem modi. Officiis optio quidem iste nihil delectus commodi. Aperiam amet omnis eum praesentium natus recusandae suscipit.
+                default_variant_id: variant_gbHJdmfrXB
+                buy_box_variant_id: variant_gbHJdmfrXB
+                thumbnail_url:
+                tags: []
+                price:
+                  id: price_gbHJdmfrXB
+                  currency: USD
+                  amount: '19.99'
+                  compare_at_amount:
+                  price_list_id:
+                  min_quantity: 1
+                  variant_id: variant_gbHJdmfrXB
+                  created_at: '2026-01-15T12:00:00.000Z'
+                  updated_at: '2026-01-15T12:00:00.000Z'
+                original_price:
+                seller_id:
+                external_references: {}
+                status: archived
+                metadata: {}
+                deleted_at:
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+                delivery_profile_id: fp_UkLWZg9DAJ
+                seller_name:
+                product_type_id:
+                tax_category_id: taxcat_UkLWZg9DAJ
+                total_on_hand: 0
+              schema:
+                "$ref": "#/components/schemas/Product"
+        '422':
+          description: the product is awaiting review
+          content:
+            application/json:
+              example:
+                error:
+                  code: product_in_review
+                  message: A product awaiting review is approved or rejected, not
+                    moved to another status
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+  "/api/v3/admin/products/{id}/draft":
+    parameters:
+    - name: id
+      in: path
+      required: true
+      description: Product ID
+      schema:
+        type: string
+    patch:
+      summary: Move a product back to draft
+      tags:
+      - Products
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const product = await client.products.draft('prod_UkLWZg9DAJ')
+      - lang: bash
+        label: Spree CLI
+        source: spree api patch /products/{id}/draft -d '{ ... }'
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Takes one product off sale, back to a draft. Runs the draft workflow, so its hooks and its event fire. A product awaiting review is refused: approve or reject it instead.
+
+
+        **Required scope:** `write_products` (for API-key authentication).
+      parameters:
+      - name: x-spree-api-key
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: Authorization
+        in: header
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: product draft
+          content:
+            application/json:
+              example:
+                id: prod_gbHJdmfrXB
+                name: Product 1682527
+                slug: product-1682527
+                meta_title:
+                meta_description:
+                meta_keywords:
+                variant_count: 1
+                available_on:
+                preorder_ships_at:
+                purchasable: true
+                preorder: false
+                in_stock: false
+                backorderable: true
+                available: false
+                description: Temporibus fugiat ducimus quae voluptas error. Iure repellat
+                  labore aperiam harum magni. Fuga ullam possimus ad repudiandae atque.
+                  Excepturi quidem est expedita molestiae delectus. Optio tempora
+                  sed minus voluptatum doloremque. Laborum esse voluptate nostrum
+                  nesciunt. Ipsum ducimus a dolor nostrum quis corrupti quae illum.
+                  Fuga provident deleniti minima ea vel. Cupiditate architecto omnis
+                  reprehenderit iusto suscipit corrupti quia cumque. Voluptatem nisi
+                  dignissimos aut nostrum distinctio quo explicabo fugiat. Unde minima
+                  ratione enim minus officia rerum odio reiciendis. Fugiat perferendis
+                  nulla voluptates voluptatum alias. Voluptatem cumque voluptatibus
+                  in sint assumenda ad neque. Inventore error consequuntur exercitationem
+                  officia consequatur earum iure autem. Odit iure porro reiciendis
+                  placeat. Animi minus vel asperiores maiores error tempora. Dolorum
+                  esse sapiente voluptatem iste culpa suscipit. Nulla sapiente sit
+                  deserunt iste totam dolores. Tempora magni eveniet natus nemo optio.
+                  Aliquid quis ullam illo minus. Atque distinctio sapiente voluptatibus
+                  adipisci consectetur repellendus culpa dolor. Dolor pariatur tempora
+                  ab repellat unde aliquam sequi. Necessitatibus aliquid fugit molestias
+                  facilis ratione.
+                description_html: |-
+                  Temporibus fugiat ducimus quae voluptas error. Iure repellat labore aperiam harum magni. Fuga ullam possimus ad repudiandae atque. Excepturi quidem est expedita molestiae delectus. Optio tempora sed minus voluptatum doloremque.
+                  Laborum esse voluptate nostrum nesciunt. Ipsum ducimus a dolor nostrum quis corrupti quae illum. Fuga provident deleniti minima ea vel. Cupiditate architecto omnis reprehenderit iusto suscipit corrupti quia cumque. Voluptatem nisi dignissimos aut nostrum distinctio quo explicabo fugiat.
+                  Unde minima ratione enim minus officia rerum odio reiciendis. Fugiat perferendis nulla voluptates voluptatum alias. Voluptatem cumque voluptatibus in sint assumenda ad neque. Inventore error consequuntur exercitationem officia consequatur earum iure autem.
+                  Odit iure porro reiciendis placeat. Animi minus vel asperiores maiores error tempora. Dolorum esse sapiente voluptatem iste culpa suscipit. Nulla sapiente sit deserunt iste totam dolores.
+                  Tempora magni eveniet natus nemo optio. Aliquid quis ullam illo minus. Atque distinctio sapiente voluptatibus adipisci consectetur repellendus culpa dolor. Dolor pariatur tempora ab repellat unde aliquam sequi. Necessitatibus aliquid fugit molestias facilis ratione.
+                default_variant_id: variant_gbHJdmfrXB
+                buy_box_variant_id: variant_gbHJdmfrXB
+                thumbnail_url:
+                tags: []
+                price:
+                  id: price_gbHJdmfrXB
+                  currency: USD
+                  amount: '19.99'
+                  compare_at_amount:
+                  price_list_id:
+                  min_quantity: 1
+                  variant_id: variant_gbHJdmfrXB
+                  created_at: '2026-01-15T12:00:00.000Z'
+                  updated_at: '2026-01-15T12:00:00.000Z'
+                original_price:
+                seller_id:
+                external_references: {}
+                status: draft
+                metadata: {}
+                deleted_at:
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+                delivery_profile_id: fp_UkLWZg9DAJ
+                seller_name:
+                product_type_id:
+                tax_category_id: taxcat_UkLWZg9DAJ
+                total_on_hand: 0
+              schema:
+                "$ref": "#/components/schemas/Product"
+        '422':
+          description: the product is awaiting review
+          content:
+            application/json:
+              example:
+                error:
+                  code: product_in_review
+                  message: A product awaiting review is approved or rejected, not
+                    moved to another status
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
   "/api/v3/admin/translations":
     get:
       summary: Translation coverage for a resource type
@@ -29886,6 +31133,13 @@ paths:
         required: true
         schema:
           type: string
+      - name: expand
+        in: query
+        required: false
+        description: 'Comma-separated associations to expand: `rules`, `actions` (each
+          under the same shape the write accepts), `custom_fields`.'
+        schema:
+          type: string
       responses:
         '200':
           description: promotion found
@@ -39578,6 +40832,77 @@ paths:
             schema:
               "$ref": "#/components/schemas/CatalogAssignParams"
         required: true
+  "/api/v3/admin/catalogs/{id}/import_products":
+    parameters:
+    - name: id
+      in: path
+      required: true
+      schema:
+        type: string
+    post:
+      summary: Import price list products into a catalog
+      tags:
+      - Catalogs
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const { added_count } = await client.catalogs.importProducts('cat_86Rf07xd4z')
+      - lang: bash
+        label: Spree CLI
+        source: spree api post /catalogs/{id}/import_products -d '{ ... }'
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Adds every product on the catalog's price list to its assortment. Products
+        already in it stay, even ones the list does not price. Refused for a
+        catalog without a price list; the count reports what was added.
+
+
+        **Required scope:** `write_products` (for API-key authentication).
+      parameters:
+      - name: x-spree-api-key
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: Authorization
+        in: header
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: products imported
+          content:
+            application/json:
+              example:
+                added_count: 1
+              schema:
+                type: object
+                properties:
+                  added_count:
+                    type: integer
+                required:
+                - added_count
+        '422':
+          description: the catalog has no price list
+          content:
+            application/json:
+              example:
+                error:
+                  code: validation_error
+                  message: This catalog has no price list to import products from.
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
   "/api/v3/admin/catalogs/{catalog_id}/products":
     get:
       summary: List catalog products
@@ -41294,6 +42619,7 @@ paths:
       summary: Reposition a collection product
       tags:
       - Collections
+      operationId: collections_reposition_product
       security:
       - api_key: []
         bearer_auth: []
@@ -43678,6 +45004,7 @@ paths:
       summary: Re-check a company tax registration
       tags:
       - Companies
+      operationId: company_tax_identifiers_validate
       security:
       - api_key: []
         bearer_auth: []
@@ -49258,6 +50585,7 @@ paths:
       summary: Buy or record a shipping label
       tags:
       - Shipping Labels
+      operationId: shipping_labels_purchase
       security:
       - api_key: []
         bearer_auth: []
@@ -51701,6 +53029,7 @@ paths:
       summary: Book in a delivery
       tags:
       - Purchase Orders
+      operationId: purchase_orders_receive
       security:
       - api_key: []
         bearer_auth: []
@@ -52332,6 +53661,9 @@ paths:
         required: true
   "/api/v3/admin/reporting/query":
     post:
+      x-spree-agent: false
+      x-spree-agent-reason: query_report runs this query, with describe_reporting
+        to learn the vocabulary first.
       summary: Run a reporting query
       tags:
       - Reports
@@ -54247,6 +55579,93 @@ paths:
             schema:
               "$ref": "#/components/schemas/SellerInviteParams"
         required: true
+  "/api/v3/admin/sellers/{seller_id}/invitations/{id}/resend":
+    parameters:
+    - name: seller_id
+      in: path
+      required: true
+      description: Seller prefixed ID
+      schema:
+        type: string
+    - name: id
+      in: path
+      required: true
+      description: Invitation prefixed ID
+      schema:
+        type: string
+    patch:
+      summary: Resend a seller invitation
+      tags:
+      - Sellers
+      x-codeSamples:
+      - lang: javascript
+        label: Spree Admin SDK
+        source: |-
+          import { createAdminClient } from '@spree/admin-sdk'
+
+          const client = createAdminClient({
+            baseUrl: 'https://your-store.com',
+            secretKey: 'sk_xxx',
+          })
+
+          const invitation = await client.sellers.invitations.resend('seller_UkLWZg9DAJ', 'inv_UkLWZg9DAJ')
+      - lang: bash
+        label: Spree CLI
+        source: spree api patch /sellers/{seller_id}/invitations/{id}/resend -d '{
+          ... }'
+      security:
+      - api_key: []
+        bearer_auth: []
+      description: |-
+        Sends a pending invitation to the seller's team again, with a fresh
+        acceptance link. Use it when the email never arrived; an invitation that
+        has expired is refused, so invite the person again instead.
+
+
+        **Required scope:** `write_sellers` (for API-key authentication).
+      parameters:
+      - name: x-spree-api-key
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: Authorization
+        in: header
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: invitation resent
+          content:
+            application/json:
+              example:
+                id: inv_UkLWZg9DAJ
+                email: gaye@rutherfordmosciski.co.uk
+                status: pending
+                created_at: '2026-01-15T12:00:00.000Z'
+                updated_at: '2026-01-15T12:00:00.000Z'
+                expires_at: '2026-01-29T12:00:00.000Z'
+                role_id: role_UkLWZg9DAJ
+                role_name: admin
+                inviter_email: carman@schambergernicolas.ca
+                invitee_exists: false
+                store:
+                  id: store_UkLWZg9DAJ
+                  name: Spree Test Store
+              schema:
+                "$ref": "#/components/schemas/Invitation"
+        '422':
+          description: the invitation has expired
+          content:
+            application/json:
+              example:
+                error:
+                  code: processing_error
+                  message: This invitation has expired. Invite them again to send
+                    a new one.
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
   "/api/v3/admin/sellers/{id}/approve":
     parameters:
     - name: id
@@ -55189,6 +56608,9 @@ paths:
       schema:
         type: string
     patch:
+      x-spree-agent: false
+      x-spree-agent-reason: Settles a payout against the payment provider, reconciling
+        against provider state an agent cannot see.
       summary: Mark a payout paid
       tags:
       - Sellers
@@ -55507,6 +56929,9 @@ paths:
                 - meta
   "/api/v3/admin/stock_levels/bulk_upsert":
     post:
+      x-spree-agent: false
+      x-spree-agent-reason: set_stock calls this endpoint already, taking stock by
+        SKU and location the way a merchant names them.
       summary: Bulk-upsert stock levels
       tags:
       - Stock
@@ -57041,6 +58466,7 @@ paths:
       summary: Count a delivery in
       tags:
       - Stock Transfers
+      operationId: stock_transfers_receive
       security:
       - api_key: []
         bearer_auth: []
@@ -62312,6 +63738,24 @@ components:
           type: array
           items:
             type: object
+            properties:
+              id:
+                type: string
+              name:
+                type: string
+                nullable: true
+              position:
+                type: number
+                nullable: true
+              stock_location_ids:
+                type: array
+                items:
+                  type: string
+            required:
+            - id
+            - name
+            - position
+            - stock_location_ids
         products_count:
           type: number
         delivery_methods_count:
@@ -63650,6 +65094,14 @@ components:
           type: array
           items:
             type: object
+            properties:
+              kind:
+                type: string
+              url:
+                type: string
+            required:
+            - kind
+            - url
         labels:
           type: array
           items:
@@ -64414,6 +65866,14 @@ components:
           type: boolean
         store:
           type: object
+          properties:
+            id:
+              type: string
+            name:
+              type: string
+          required:
+          - id
+          - name
       required:
       - id
       - email
@@ -67750,6 +69210,14 @@ components:
           type: boolean
           description: Whether the card issuer reported that the security code did
             not match.
+        can_void:
+          type: boolean
+          description: Whether the payment can be voided now, as decided by its payment
+            method.
+        can_capture:
+          type: boolean
+          description: Whether the payment can be captured now, as decided by its
+            payment method.
         captured_amount:
           type: string
         order_id:
@@ -67788,6 +69256,8 @@ components:
       - updated_at
       - avs_risky
       - cvv_risky
+      - can_void
+      - can_capture
       - captured_amount
       - order_id
       x-typelizer: true
@@ -68853,6 +70323,9 @@ components:
         tax_category_id:
           type: string
           nullable: true
+        total_on_hand:
+          type: number
+          nullable: true
         digital_assets:
           type: array
           items:
@@ -68905,6 +70378,7 @@ components:
       - seller_name
       - product_type_id
       - tax_category_id
+      - total_on_hand
       x-typelizer: true
     ProductSubmission:
       type: object
@@ -69214,6 +70688,14 @@ components:
           type: array
           items:
             type: string
+        rules:
+          type: array
+          items:
+            "$ref": "#/components/schemas/PromotionRule"
+        actions:
+          type: array
+          items:
+            "$ref": "#/components/schemas/PromotionAction"
       required:
       - id
       - name
@@ -70033,6 +71515,14 @@ components:
           type: array
           items:
             type: object
+            properties:
+              kind:
+                type: string
+              url:
+                type: string
+            required:
+            - kind
+            - url
         labels:
           type: array
           items:
@@ -70856,6 +72346,15 @@ components:
           nullable: true
         blocker:
           type: object
+          properties:
+            state:
+              type: string
+            message:
+              type: string
+              nullable: true
+          required:
+          - state
+          - message
           nullable: true
         blocking:
           type: boolean
@@ -71034,6 +72533,14 @@ components:
           type: number
         onboarding_progress:
           type: object
+          properties:
+            done:
+              type: number
+            total:
+              type: number
+          required:
+          - done
+          - total
         onboarding_complete:
           type: boolean
         legal_name: