Skip to content

armgit / spree

Public Imported from GitHub
0

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

Added the missing Seller API endpoints to the API reference

Damian Legawiec56878d565bb9
diff --git a/packages/seller-sdk/examples/imports/delete.ts b/packages/seller-sdk/examples/imports/delete.ts
new file mode 100644
index 0000000000..f88bdafa97
--- /dev/null
+++ b/packages/seller-sdk/examples/imports/delete.ts
@@ -0,0 +1,11 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+await client.imports.delete('imp_UkLWZg9DAJ')
+// endregion:example
diff --git a/packages/seller-sdk/examples/imports/download.ts b/packages/seller-sdk/examples/imports/download.ts
new file mode 100644
index 0000000000..7a45dd8cf3
--- /dev/null
+++ b/packages/seller-sdk/examples/imports/download.ts
@@ -0,0 +1,26 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const productImport = await client.imports.get('imp_UkLWZg9DAJ')
+
+if (productImport.original_file_url) {
+ // The uploaded file is served through the API, so fetch it with the
+ // session's token and seller, then drive the browser download:
+ const response = await fetch(`https://your-store.com${productImport.original_file_url}`, {
+ headers: { Authorization: 'Bearer eyJhbGciOi...', 'X-Spree-Seller-Id': 'sel_UkLWZg9DAJ' },
+ })
+ const url = URL.createObjectURL(await response.blob())
+ const link = Object.assign(document.createElement('a'), {
+ href: url,
+ download: productImport.original_filename ?? 'import.csv',
+ })
+ link.click()
+ URL.revokeObjectURL(url)
+}
+// endregion:example
diff --git a/packages/seller-sdk/examples/imports/get.ts b/packages/seller-sdk/examples/imports/get.ts
new file mode 100644
index 0000000000..467c9eee5a
--- /dev/null
+++ b/packages/seller-sdk/examples/imports/get.ts
@@ -0,0 +1,14 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const productImport = await client.imports.get('imp_UkLWZg9DAJ')
+
+// endregion:example
+
+export { productImport }
diff --git a/packages/seller-sdk/examples/imports/retry-failed-rows.ts b/packages/seller-sdk/examples/imports/retry-failed-rows.ts
new file mode 100644
index 0000000000..2248b996e3
--- /dev/null
+++ b/packages/seller-sdk/examples/imports/retry-failed-rows.ts
@@ -0,0 +1,14 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const productImport = await client.imports.retryFailedRows('imp_UkLWZg9DAJ')
+
+// endregion:example
+
+export { productImport }
diff --git a/packages/seller-sdk/examples/invitations/delete.ts b/packages/seller-sdk/examples/invitations/delete.ts
index b58002abf3..abbce16bde 100644
--- a/packages/seller-sdk/examples/invitations/delete.ts
+++ b/packages/seller-sdk/examples/invitations/delete.ts
@@ -7,5 +7,5 @@ const client = createSellerClient({
})
// region:example
-await client.invitations.revoke('inv_xxx')
+await client.invitations.delete('inv_xxx')
// endregion:example
diff --git a/packages/seller-sdk/examples/order-claims/get.ts b/packages/seller-sdk/examples/order-claims/get.ts
new file mode 100644
index 0000000000..873adf557b
--- /dev/null
+++ b/packages/seller-sdk/examples/order-claims/get.ts
@@ -0,0 +1,14 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const claim = await client.orders.claims.get('or_UkLWZg9DAJ', 'claim_UkLWZg9DAJ')
+
+// endregion:example
+
+export { claim }
diff --git a/packages/seller-sdk/examples/order-deliveries/delete.ts b/packages/seller-sdk/examples/order-deliveries/delete.ts
new file mode 100644
index 0000000000..a26e02a501
--- /dev/null
+++ b/packages/seller-sdk/examples/order-deliveries/delete.ts
@@ -0,0 +1,15 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+await client.orders.fulfillments.deliveries.delete(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ 'dlv_UkLWZg9DAJ',
+)
+// endregion:example
diff --git a/packages/seller-sdk/examples/order-deliveries/get.ts b/packages/seller-sdk/examples/order-deliveries/get.ts
new file mode 100644
index 0000000000..7399d9c45b
--- /dev/null
+++ b/packages/seller-sdk/examples/order-deliveries/get.ts
@@ -0,0 +1,18 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const delivery = await client.orders.fulfillments.deliveries.get(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ 'dlv_UkLWZg9DAJ',
+)
+
+// endregion:example
+
+export { delivery }
diff --git a/packages/seller-sdk/examples/order-exchanges/approve.ts b/packages/seller-sdk/examples/order-exchanges/approve.ts
new file mode 100644
index 0000000000..1c75a4bead
--- /dev/null
+++ b/packages/seller-sdk/examples/order-exchanges/approve.ts
@@ -0,0 +1,14 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const exchange = await client.orders.exchanges.approve('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ')
+
+// endregion:example
+
+export { exchange }
diff --git a/packages/seller-sdk/examples/order-exchanges/get.ts b/packages/seller-sdk/examples/order-exchanges/get.ts
new file mode 100644
index 0000000000..cbd86d2c61
--- /dev/null
+++ b/packages/seller-sdk/examples/order-exchanges/get.ts
@@ -0,0 +1,14 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const exchange = await client.orders.exchanges.get('or_UkLWZg9DAJ', 'exch_UkLWZg9DAJ')
+
+// endregion:example
+
+export { exchange }
diff --git a/packages/seller-sdk/examples/order-fulfillments/get.ts b/packages/seller-sdk/examples/order-fulfillments/get.ts
new file mode 100644
index 0000000000..d9356685a4
--- /dev/null
+++ b/packages/seller-sdk/examples/order-fulfillments/get.ts
@@ -0,0 +1,14 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const fulfillment = await client.orders.fulfillments.get('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
+
+// endregion:example
+
+export { fulfillment }
diff --git a/packages/seller-sdk/examples/order-labels/delete.ts b/packages/seller-sdk/examples/order-labels/delete.ts
new file mode 100644
index 0000000000..c02479a84c
--- /dev/null
+++ b/packages/seller-sdk/examples/order-labels/delete.ts
@@ -0,0 +1,11 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+await client.orders.fulfillments.labels.delete('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', 'lbl_UkLWZg9DAJ')
+// endregion:example
diff --git a/packages/seller-sdk/examples/order-labels/download.ts b/packages/seller-sdk/examples/order-labels/download.ts
new file mode 100644
index 0000000000..7a53e617b9
--- /dev/null
+++ b/packages/seller-sdk/examples/order-labels/download.ts
@@ -0,0 +1,25 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const label = await client.orders.fulfillments.labels.get(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ 'lbl_UkLWZg9DAJ',
+)
+
+if (label.download_url) {
+ // Labels are served through the API, so fetch with the session's token
+ // and seller, then open the file for printing:
+ const response = await fetch(`https://your-store.com${label.download_url}`, {
+ headers: { Authorization: 'Bearer eyJhbGciOi...', 'X-Spree-Seller-Id': 'sel_UkLWZg9DAJ' },
+ })
+ const url = URL.createObjectURL(await response.blob())
+ window.open(url)
+}
+// endregion:example
diff --git a/packages/seller-sdk/examples/order-labels/get.ts b/packages/seller-sdk/examples/order-labels/get.ts
new file mode 100644
index 0000000000..f7c0c02e7e
--- /dev/null
+++ b/packages/seller-sdk/examples/order-labels/get.ts
@@ -0,0 +1,18 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const label = await client.orders.fulfillments.labels.get(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ 'lbl_UkLWZg9DAJ',
+)
+
+// endregion:example
+
+export { label }
diff --git a/packages/seller-sdk/examples/order-returns/get.ts b/packages/seller-sdk/examples/order-returns/get.ts
new file mode 100644
index 0000000000..9b8fe34684
--- /dev/null
+++ b/packages/seller-sdk/examples/order-returns/get.ts
@@ -0,0 +1,14 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const orderReturn = await client.orders.returns.get('or_UkLWZg9DAJ', 'ret_UkLWZg9DAJ')
+
+// endregion:example
+
+export { orderReturn }
diff --git a/packages/seller-sdk/examples/products/archive.ts b/packages/seller-sdk/examples/products/archive.ts
new file mode 100644
index 0000000000..2b0bbc8a5f
--- /dev/null
+++ b/packages/seller-sdk/examples/products/archive.ts
@@ -0,0 +1,14 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const product = await client.products.archive('prod_UkLWZg9DAJ')
+
+// endregion:example
+
+export { product }
diff --git a/packages/seller-sdk/examples/products/bulk-destroy.ts b/packages/seller-sdk/examples/products/bulk-destroy.ts
new file mode 100644
index 0000000000..80e1cde30b
--- /dev/null
+++ b/packages/seller-sdk/examples/products/bulk-destroy.ts
@@ -0,0 +1,16 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const result = await client.products.bulkDestroy({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+})
+
+// endregion:example
+
+export { result }
diff --git a/packages/seller-sdk/examples/products/draft.ts b/packages/seller-sdk/examples/products/draft.ts
new file mode 100644
index 0000000000..43832798cc
--- /dev/null
+++ b/packages/seller-sdk/examples/products/draft.ts
@@ -0,0 +1,14 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const product = await client.products.draft('prod_UkLWZg9DAJ')
+
+// endregion:example
+
+export { product }
diff --git a/packages/seller-sdk/examples/products/submit.ts b/packages/seller-sdk/examples/products/submit.ts
new file mode 100644
index 0000000000..b6652b57a8
--- /dev/null
+++ b/packages/seller-sdk/examples/products/submit.ts
@@ -0,0 +1,14 @@
+import { createSellerClient } from '@spree/seller-sdk'
+
+const client = createSellerClient({
+ baseUrl: 'https://your-store.com',
+ jwtToken: 'eyJhbGciOi...',
+ sellerId: 'sel_UkLWZg9DAJ',
+})
+
+// region:example
+const product = await client.products.submit('prod_UkLWZg9DAJ')
+
+// endregion:example
+
+export { product }
diff --git a/packages/seller-sdk/examples/tax-identifiers/delete.ts b/packages/seller-sdk/examples/tax-identifiers/delete.ts
index 2ddc880335..467534d6e4 100644
--- a/packages/seller-sdk/examples/tax-identifiers/delete.ts
+++ b/packages/seller-sdk/examples/tax-identifiers/delete.ts
@@ -7,5 +7,5 @@ const client = createSellerClient({
})
// region:example
-await client.taxIdentifiers.remove('txi_xxx')
+await client.taxIdentifiers.delete('txi_xxx')
// endregion:example
diff --git a/packages/seller-sdk/examples/team/delete.ts b/packages/seller-sdk/examples/team/delete.ts
index b1f8a68c2f..1d99810a06 100644
--- a/packages/seller-sdk/examples/team/delete.ts
+++ b/packages/seller-sdk/examples/team/delete.ts
@@ -7,5 +7,5 @@ const client = createSellerClient({
})
// region:example
-await client.team.remove('adm_xxx')
+await client.team.delete('adm_xxx')
// endregion:example
diff --git a/packages/seller-sdk/src/types/params/ProductBulkDestroyParams.ts b/packages/seller-sdk/src/types/params/ProductBulkDestroyParams.ts
new file mode 100644
index 0000000000..da624d7e85
--- /dev/null
+++ b/packages/seller-sdk/src/types/params/ProductBulkDestroyParams.ts
@@ -0,0 +1,9 @@
+// This file is auto-generated from the request schemas in docs/api-reference by `pnpm generate:params`. Do not edit directly.
+
+export type ProductBulkDestroyParams = {
+ /**
+ * Ids outside this seller's catalog are ignored; products the store refuses to delete are counted
+ * in `skipped_count`.
+ */
+ ids: string[]
+}
diff --git a/packages/seller-sdk/src/types/params/index.ts b/packages/seller-sdk/src/types/params/index.ts
index b8805a64e4..bc7f1dc1dc 100644
--- a/packages/seller-sdk/src/types/params/index.ts
+++ b/packages/seller-sdk/src/types/params/index.ts
@@ -34,6 +34,7 @@ export type { PasswordResetCreateParams } from './PasswordResetCreateParams'
export type { PasswordResetUpdateParams } from './PasswordResetUpdateParams'
export type { PolicyCreateParams } from './PolicyCreateParams'
export type { PolicyUpdateParams } from './PolicyUpdateParams'
+export type { ProductBulkDestroyParams } from './ProductBulkDestroyParams'
export type { ProductBulkStatusParams } from './ProductBulkStatusParams'
export type { ProductBulkSubmitParams } from './ProductBulkSubmitParams'
export type { ProductCreateParams } from './ProductCreateParams'
diff --git a/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb
index cc0e065994..33648d0769 100644
--- a/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/seller/products_controller.rb
@@ -142,6 +142,12 @@ module Spree
description: 'Only drafts and rejected listings are submitted; the rest are counted in `skipped_count`.'
end
+ request_params 'ProductBulkDestroyParams', action: :bulk_destroy do |body|
+ body.attribute :ids, :array, of: :id,
+ required: true,
+ description: "Ids outside this seller's catalog are ignored; products the store refuses to delete are counted in `skipped_count`."
+ end
+
request_params 'ProductBulkStatusParams', action: :bulk_status_update do |body|
body.attribute :ids, :array, of: :id, required: true, example: ['prod_UkLWZg9DAJ']
body.attribute :status, :string,
diff --git a/spree/api/spec/integration/spree/api/v3/seller/claims_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/claims_spec.rb
index b74457a330..54711ed2f4 100644
--- a/spree/api/spec/integration/spree/api/v3/seller/claims_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/seller/claims_spec.rb
@@ -84,6 +84,35 @@ RSpec.describe 'Seller Claims API', type: :request, swagger_doc: 'api-reference/
end
end
+ path '/api/v3/seller/orders/{order_id}/claims/{id}' do
+ parameter name: :order_id, in: :path, type: :string, description: 'Prefixed order ID'
+ parameter name: :id, in: :path, type: :string, description: 'Prefixed claim ID'
+
+ get 'Show a claim' do
+ tags 'Claims'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description "One problem reported on one of this seller's orders, with the items it covers and the reason given."
+
+ seller_sdk_example 'order-claims/get'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'claim found' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:id) { claim.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/Claim'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['id']).to eq(claim.prefixed_id)
+ end
+ end
+ end
+ end
+
path '/api/v3/seller/orders/{order_id}/claims/{id}/approve' do
parameter name: :order_id, in: :path, type: :string
parameter name: :id, in: :path, type: :string
diff --git a/spree/api/spec/integration/spree/api/v3/seller/exchanges_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/exchanges_spec.rb
index 8059577fd3..5eec91b49a 100644
--- a/spree/api/spec/integration/spree/api/v3/seller/exchanges_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/seller/exchanges_spec.rb
@@ -90,6 +90,64 @@ RSpec.describe 'Seller Exchanges API', type: :request, swagger_doc: 'api-referen
end
end
+ path '/api/v3/seller/orders/{order_id}/exchanges/{id}' do
+ parameter name: :order_id, in: :path, type: :string, description: 'Prefixed order ID'
+ parameter name: :id, in: :path, type: :string, description: 'Prefixed exchange ID'
+
+ get 'Show an exchange' do
+ tags 'Exchanges'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description "One exchange on one of this seller's orders, with what is coming back and what goes out in its place."
+
+ seller_sdk_example 'order-exchanges/get'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'exchange found' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:id) { exchange.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/Exchange'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['id']).to eq(exchange.prefixed_id)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/seller/orders/{order_id}/exchanges/{id}/approve' do
+ parameter name: :order_id, in: :path, type: :string
+ parameter name: :id, in: :path, type: :string
+
+ patch 'Approve an exchange' do
+ tags 'Exchanges'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description 'Agrees to the swap, so the customer can send the original goods back.'
+
+ seller_sdk_example 'order-exchanges/approve'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'exchange approved' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:id) { exchange.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/Exchange'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['status']).to eq('approved')
+ end
+ end
+ end
+ end
+
path '/api/v3/seller/orders/{order_id}/exchanges/{id}/receive' do
parameter name: :order_id, in: :path, type: :string
parameter name: :id, in: :path, type: :string
diff --git a/spree/api/spec/integration/spree/api/v3/seller/fulfillments_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/fulfillments_spec.rb
index 5abdc7cd97..d77b595399 100644
--- a/spree/api/spec/integration/spree/api/v3/seller/fulfillments_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/seller/fulfillments_spec.rb
@@ -99,6 +99,30 @@ RSpec.describe 'Seller Fulfillments API', type: :request, swagger_doc: 'api-refe
parameter name: :order_id, in: :path, type: :string
parameter name: :id, in: :path, type: :string
+ get 'Show a fulfillment' do
+ tags 'Fulfillments'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description "One of this seller's parcels: what it holds, where it ships from and how it is tracked."
+
+ seller_sdk_example 'order-fulfillments/get'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'fulfillment found' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:id) { fulfillment.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/Fulfillment'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['id']).to eq(fulfillment.prefixed_id)
+ end
+ end
+ end
+
patch 'Update tracking' do
tags 'Fulfillments'
consumes 'application/json'
@@ -264,6 +288,31 @@ RSpec.describe 'Seller Fulfillments API', type: :request, swagger_doc: 'api-refe
parameter name: :fulfillment_id, in: :path, type: :string, description: 'Prefixed fulfillment ID'
parameter name: :id, in: :path, type: :string, description: 'Prefixed delivery ID'
+ get 'Show a delivery' do
+ tags 'Fulfillments'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description "One consignment of one of this seller's parcels, with its tracking number and carrier status."
+
+ seller_sdk_example 'order-deliveries/get'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'delivery found' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { fulfillment.prefixed_id }
+ let(:id) { fulfillment.deliveries.first.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/Delivery'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['id']).to eq(fulfillment.deliveries.first.prefixed_id)
+ end
+ end
+ end
+
patch 'Correct a delivery' do
tags 'Fulfillments'
consumes 'application/json'
@@ -291,6 +340,30 @@ RSpec.describe 'Seller Fulfillments API', type: :request, swagger_doc: 'api-refe
end
end
end
+
+ delete 'Delete a delivery' do
+ tags 'Fulfillments'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description 'Removes a consignment entered by mistake. One that a label created is refused — delete the label instead.'
+
+ seller_sdk_example 'order-deliveries/delete'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '204', 'delivery deleted' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { fulfillment.prefixed_id }
+ let!(:delivery) { fulfillment.deliveries.first }
+ let(:id) { delivery.prefixed_id }
+
+ run_test! do
+ expect(Spree::Delivery.exists?(delivery.id)).to be(false)
+ end
+ end
+ end
end
path '/api/v3/seller/orders/{order_id}/fulfillments/{fulfillment_id}/labels' do
@@ -367,6 +440,100 @@ RSpec.describe 'Seller Fulfillments API', type: :request, swagger_doc: 'api-refe
end
end
+ path '/api/v3/seller/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}' do
+ parameter name: :order_id, in: :path, type: :string, description: 'Prefixed order ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, description: 'Prefixed fulfillment ID'
+ parameter name: :id, in: :path, type: :string, description: 'Prefixed shipping label ID'
+
+ get 'Show a shipping label' do
+ tags 'Fulfillments'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description "One label on one of this seller's parcels, with the link to print it."
+
+ seller_sdk_example 'order-labels/get'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'label found' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { fulfillment.prefixed_id }
+ let(:shipping_label) { create(:shipping_label, :uploaded, :with_file, owner: fulfillment, store: store) }
+ let(:id) { shipping_label.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/ShippingLabel'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['id']).to eq(shipping_label.prefixed_id)
+ end
+ end
+ end
+
+ delete 'Delete an uploaded label' do
+ tags 'Fulfillments'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description <<~DESC
+ Removes a label uploaded by mistake, so the right one can be uploaded
+ in its place. A label the marketplace bought has postage to refund, so
+ only the operator can remove it.
+ DESC
+
+ seller_sdk_example 'order-labels/delete'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '204', 'label deleted' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { fulfillment.prefixed_id }
+ let(:shipping_label) { create(:shipping_label, :uploaded, :with_file, owner: fulfillment, store: store) }
+ let(:id) { shipping_label.prefixed_id }
+
+ run_test! do
+ expect(Spree::ShippingLabel.exists?(shipping_label.id)).to be(false)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/seller/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/download' do
+ parameter name: :order_id, in: :path, type: :string, description: 'Prefixed order ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, description: 'Prefixed fulfillment ID'
+ parameter name: :id, in: :path, type: :string, description: 'Prefixed shipping label ID'
+
+ get 'Download a shipping label' do
+ tags 'Fulfillments'
+ produces 'application/pdf', 'image/png', 'application/octet-stream'
+ security [bearer_auth: []]
+ description <<~DESC
+ Streams the label file for printing.
+
+ Served through the API rather than from a storage URL, so the seller's
+ own session authorizes every download.
+ DESC
+
+ seller_sdk_example 'order-labels/download'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'label file streamed' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { fulfillment.prefixed_id }
+ let(:id) { create(:shipping_label, :uploaded, :with_file, owner: fulfillment, store: store).prefixed_id }
+
+ run_test! do |response|
+ expect(response.body).to start_with('%PDF')
+ end
+ end
+ end
+ end
+
path '/api/v3/seller/tracking_carriers' do
get 'List tracking carriers' do
tags 'Fulfillments'
diff --git a/spree/api/spec/integration/spree/api/v3/seller/imports_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/imports_spec.rb
index c38dc40dc0..3a3dd0329d 100644
--- a/spree/api/spec/integration/spree/api/v3/seller/imports_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/seller/imports_spec.rb
@@ -83,6 +83,66 @@ RSpec.describe 'Seller Imports API', type: :request, swagger_doc: 'api-reference
end
end
+ path '/api/v3/seller/imports/{id}' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Import prefixed ID'
+
+ get 'Get an import' do
+ tags 'Imports'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description <<~DESC
+ One of this seller's imports. Poll it while `status` is `completed_mapping`
+ or `processing`; `completed` and `failed` are final. An id belonging to
+ another seller answers `404`.
+ DESC
+
+ seller_sdk_example 'imports/get'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'import returned' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:id) { product_import.prefixed_id }
+
+ schema SwaggerSchemaHelpers.ref('Import')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['id']).to eq(product_import.prefixed_id)
+ end
+ end
+
+ response '404', "another seller's import" do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:id) { create(:product_import, :for_seller, store: store).prefixed_id }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ delete 'Delete an import' do
+ tags 'Imports'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description "Deletes one of this seller's imports together with its rows. Products it already created are kept."
+
+ seller_sdk_example 'imports/delete'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '204', 'import deleted' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:id) { product_import.prefixed_id }
+
+ run_test!
+ end
+ end
+ end
+
path '/api/v3/seller/imports/{import_id}/rows' do
parameter name: :import_id, in: :path, type: :string, required: true, description: 'Import prefixed ID'
@@ -150,4 +210,84 @@ RSpec.describe 'Seller Imports API', type: :request, swagger_doc: 'api-reference
end
end
end
+
+ path '/api/v3/seller/imports/{id}/retry_failed_rows' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Import prefixed ID'
+
+ patch 'Retry failed rows' do
+ tags 'Imports'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description <<~DESC
+ Processes the rows that failed again, typically after fixing what they
+ referred to. The import goes back to `processing`; poll
+ `GET /imports/{id}` until it finishes. Returns 422 when the import has
+ no failed rows to retry.
+ DESC
+
+ seller_sdk_example 'imports/retry-failed-rows'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'retry queued' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:id) do
+ product_import.tap do |import|
+ import.update_columns(status: 'completed')
+ create(:import_row, import: import, row_number: 1, status: 'failed', validation_errors: 'Price is missing')
+ end.prefixed_id
+ end
+
+ schema SwaggerSchemaHelpers.ref('Import')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['status']).to eq('processing')
+ end
+ end
+
+ response '422', 'no failed rows to retry' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:id) { product_import.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/seller/imports/{id}/download' do
+ parameter name: :id, in: :path, type: :string, required: true, description: 'Import prefixed ID'
+
+ get 'Download the uploaded file' do
+ tags 'Imports'
+ produces 'text/csv'
+ security [bearer_auth: []]
+ description <<~DESC
+ Streams the CSV exactly as the seller uploaded it — a record of what was
+ imported.
+
+ The bytes are served by this endpoint rather than through a redirect,
+ so the seller's own session authorizes every download.
+ DESC
+
+ seller_sdk_example 'imports/download'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'CSV file' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:id) { product_import.prefixed_id }
+
+ schema type: :string, format: :binary
+
+ run_test! do |response|
+ expect(response.content_type).to include('text/csv')
+ end
+ end
+ end
+ end
end
diff --git a/spree/api/spec/integration/spree/api/v3/seller/products_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/products_spec.rb
index d0def6040c..a7febbbe78 100644
--- a/spree/api/spec/integration/spree/api/v3/seller/products_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/seller/products_spec.rb
@@ -177,6 +177,108 @@ RSpec.describe 'Seller Products API', type: :request, swagger_doc: 'api-referenc
end
end
+ path '/api/v3/seller/products/{id}/submit' do
+ parameter name: :id, in: :path, type: :string, description: 'Product ID'
+
+ patch 'Submit a product for review' do
+ tags 'Products'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description <<~DESC
+ Asks the marketplace to put a product on sale. Whether a listing goes
+ live is the operator's decision, so a seller submits it for review
+ rather than setting its status. Only drafts and rejected listings can
+ be submitted.
+
+ Where the marketplace approves seller products automatically, the
+ product comes back already `active`.
+ DESC
+
+ seller_sdk_example 'products/submit'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'product submitted' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:id) { create(:product, store: store, seller: seller, status: 'draft').prefixed_id }
+
+ schema '$ref' => '#/components/schemas/Product'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['status']).to eq('proposed')
+ end
+ end
+
+ response '422', 'product cannot be submitted' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:id) { product.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/seller/products/{id}/draft' do
+ parameter name: :id, in: :path, type: :string, description: 'Product ID'
+
+ patch 'Move a product back to draft' do
+ tags 'Products'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description <<~DESC
+ Takes a listing down. Withdrawing your own product is not a review
+ decision, so it needs nobody's approval.
+ DESC
+
+ seller_sdk_example 'products/draft'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'product moved to draft' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:id) { product.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/Product'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['status']).to eq('draft')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/seller/products/{id}/archive' do
+ parameter name: :id, in: :path, type: :string, description: 'Product ID'
+
+ patch 'Archive a product' do
+ tags 'Products'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description 'Retires a product the acting seller owns, taking it off sale without deleting it.'
+
+ seller_sdk_example 'products/archive'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'product archived' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:id) { product.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/Product'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['status']).to eq('archived')
+ end
+ end
+ end
+ end
+
path '/api/v3/seller/products/bulk_submit' do
post 'Submit products for review' do
tags 'Products'
@@ -235,4 +337,34 @@ RSpec.describe 'Seller Products API', type: :request, swagger_doc: 'api-referenc
end
end
end
+
+ path '/api/v3/seller/products/bulk_destroy' do
+ delete 'Delete products' do
+ tags 'Products'
+ consumes 'application/json'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description <<~DESC
+ Deletes a selection of the acting seller's products. Ids outside this
+ seller's catalog are ignored. A product the marketplace refuses to
+ delete is skipped: `product_count` is what was deleted, and
+ `skipped_count`, present only when something was skipped, is the rest.
+ DESC
+
+ seller_sdk_example 'products/bulk-destroy'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+ request_body_for
+
+ response '200', 'products deleted' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:body) { { ids: [product.prefixed_id] } }
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['product_count']).to eq(1)
+ end
+ end
+ end
+ end
end
diff --git a/spree/api/spec/integration/spree/api/v3/seller/returns_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/returns_spec.rb
index 6f67753dc3..f2da11fa06 100644
--- a/spree/api/spec/integration/spree/api/v3/seller/returns_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/seller/returns_spec.rb
@@ -103,6 +103,35 @@ RSpec.describe 'Seller Returns API', type: :request, swagger_doc: 'api-reference
end
end
+ path '/api/v3/seller/orders/{order_id}/returns/{id}' do
+ parameter name: :order_id, in: :path, type: :string, description: 'Prefixed order ID'
+ parameter name: :id, in: :path, type: :string, description: 'Prefixed return ID'
+
+ get 'Show a return' do
+ tags 'Returns'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description "One return on one of this seller's orders, with the goods coming back and the reason given."
+
+ seller_sdk_example 'order-returns/get'
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+
+ response '200', 'return found' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:id) { return_record.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/Return'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['id']).to eq(return_record.prefixed_id)
+ end
+ end
+ end
+ end
+
path '/api/v3/seller/orders/{order_id}/returns/{id}/approve' do
parameter name: :order_id, in: :path, type: :string
parameter name: :id, in: :path, type: :string