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.

Add customer returns and claims to the storefront SDK

Damian Legawiec680a0eda9bd0
diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.ts
index c99759ca8b..ad6e86e18b 100644
--- a/packages/sdk/src/store-client.ts
+++ b/packages/sdk/src/store-client.ts
@@ -15,6 +15,7 @@ import type {
Category,
CategoryListParams,
Channel,
+ Claim,
CompletePaymentSessionParams,
CompletePaymentSetupSessionParams,
Country,
@@ -44,6 +45,7 @@ import type {
RegisterParams,
RequestPasswordResetParams,
ResetPasswordParams,
+ Return,
StockLocation,
StoreCredit,
UpdateCartParams,
@@ -651,6 +653,102 @@ export class StoreClient {
...options,
params: getParams(params),
}),
+
+ /**
+ * Returns the customer opened on this order.
+ *
+ * Opening one is all a customer can do — approving, receiving and
+ * refunding are the merchant's, through the Admin API. Whether they may
+ * open one at all is store policy, enforced by a `returns.create.validate`
+ * handler on the server; a rejected request comes back as a 422.
+ */
+ returns: {
+ list: (
+ orderId: string,
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<Return>> =>
+ this.request<PaginatedResponse<Return>>('GET', `/orders/${orderId}/returns`, {
+ ...options,
+ params: params ? transformListParams({ ...params }) : undefined,
+ }),
+
+ get: (
+ orderId: string,
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<Return> =>
+ this.request<Return>('GET', `/orders/${orderId}/returns/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ /**
+ * @param params.items the fulfilled units coming back. `fulfillment_item_id`
+ * rather than a line item id, because a return is against a shipped unit.
+ */
+ create: (
+ orderId: string,
+ params: {
+ items: Array<{ fulfillment_item_id: string; quantity: number }>
+ reason_id?: string
+ memo?: string
+ },
+ options?: RequestOptions,
+ ): Promise<Return> =>
+ this.request<Return>('POST', `/orders/${orderId}/returns`, {
+ ...options,
+ body: params,
+ }),
+ },
+
+ /**
+ * Claims the customer filed on this order — a damaged, missing or wrong
+ * item. Nothing has to come back, so unlike a return this works whether or
+ * not the order shipped. Approving, denying and resolving are the
+ * merchant's.
+ */
+ claims: {
+ list: (
+ orderId: string,
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<Claim>> =>
+ this.request<PaginatedResponse<Claim>>('GET', `/orders/${orderId}/claims`, {
+ ...options,
+ params: params ? transformListParams({ ...params }) : undefined,
+ }),
+
+ get: (
+ orderId: string,
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<Claim> =>
+ this.request<Claim>('GET', `/orders/${orderId}/claims/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ /**
+ * @param params.claim_type one of the store's configured claim types
+ * (`damaged`, `missing`, `wrong_item`, `other` by default)
+ */
+ create: (
+ orderId: string,
+ params: {
+ items: Array<{ line_item_id: string; quantity: number; description?: string }>
+ claim_type?: string
+ memo?: string
+ },
+ options?: RequestOptions,
+ ): Promise<Claim> =>
+ this.request<Claim>('POST', `/orders/${orderId}/claims`, {
+ ...options,
+ body: params,
+ }),
+ },
}
// ============================================
diff --git a/packages/sdk/src/types/index.ts b/packages/sdk/src/types/index.ts
index 2d03292604..5cebaab64c 100644
--- a/packages/sdk/src/types/index.ts
+++ b/packages/sdk/src/types/index.ts
@@ -8,6 +8,8 @@ export type {
Cart,
Category,
Channel,
+ Claim,
+ ClaimLineItem,
Country,
CreditCard,
Currency,
@@ -41,8 +43,10 @@ export type {
Product,
Promotion,
Refund,
+ Return,
ReturnAuthorization,
ReturnItem,
+ ReturnLineItem,
State,
StockLocation,
StoreCredit,
diff --git a/packages/sdk/tests/mocks/handlers.ts b/packages/sdk/tests/mocks/handlers.ts
index 8f8a991270..0ade68a255 100644
--- a/packages/sdk/tests/mocks/handlers.ts
+++ b/packages/sdk/tests/mocks/handlers.ts
@@ -37,6 +37,25 @@ export const fixtures = {
payment_status: 'paid',
items: [],
},
+ return: {
+ id: 'ret_1',
+ number: 'RET123456789',
+ status: 'requested',
+ order_id: 'or_1',
+ refund_total: '19.99',
+ display_refund_total: '$19.99',
+ return_line_items: [],
+ },
+ claim: {
+ id: 'claim_1',
+ number: 'CLM123456789',
+ status: 'open',
+ claim_type: 'damaged',
+ order_id: 'or_1',
+ refund_total: '19.99',
+ display_refund_total: '$19.99',
+ claim_line_items: [],
+ },
lineItem: {
id: 'li_1',
quantity: 2,
@@ -385,6 +404,28 @@ export const handlers = [
// Orders (read-only, single lookup)
http.get(`${API_PREFIX}/orders/:id`, () => HttpResponse.json(fixtures.order)),
+ // Customer self-service returns and claims
+ http.get(`${API_PREFIX}/orders/:orderId/returns`, () =>
+ HttpResponse.json({
+ data: [fixtures.return],
+ meta: { page: 1, limit: 25, count: 1, pages: 1, from: 1, to: 1 },
+ }),
+ ),
+ http.get(`${API_PREFIX}/orders/:orderId/returns/:id`, () => HttpResponse.json(fixtures.return)),
+ http.post(`${API_PREFIX}/orders/:orderId/returns`, () =>
+ HttpResponse.json(fixtures.return, { status: 201 }),
+ ),
+ http.get(`${API_PREFIX}/orders/:orderId/claims`, () =>
+ HttpResponse.json({
+ data: [fixtures.claim],
+ meta: { page: 1, limit: 25, count: 1, pages: 1, from: 1, to: 1 },
+ }),
+ ),
+ http.get(`${API_PREFIX}/orders/:orderId/claims/:id`, () => HttpResponse.json(fixtures.claim)),
+ http.post(`${API_PREFIX}/orders/:orderId/claims`, () =>
+ HttpResponse.json(fixtures.claim, { status: 201 }),
+ ),
+
// Customer
http.get(`${API_PREFIX}/customers/me`, () => HttpResponse.json(fixtures.user)),
diff --git a/packages/sdk/tests/post-sale.test.ts b/packages/sdk/tests/post-sale.test.ts
new file mode 100644
index 0000000000..dd3be3a788
--- /dev/null
+++ b/packages/sdk/tests/post-sale.test.ts
@@ -0,0 +1,81 @@
+import { beforeAll, describe, expect, it } from 'vitest'
+import type { Client } from '../src'
+import { createTestClient } from './helpers'
+
+describe('customer self-service returns and claims', () => {
+ let client: Client
+ beforeAll(() => {
+ client = createTestClient()
+ })
+
+ const opts = { token: 'user-jwt' }
+
+ describe('returns', () => {
+ it('lists returns the customer opened on an order', async () => {
+ const result = await client.orders.returns.list('or_abc123', undefined, opts)
+
+ expect(result.data).toHaveLength(1)
+ expect(result.data[0].number).toBe('RET123456789')
+ expect(result.data[0].status).toBe('requested')
+ })
+
+ it('fetches a single return', async () => {
+ const result = await client.orders.returns.get('or_abc123', 'ret_1', undefined, opts)
+
+ expect(result.id).toBe('ret_1')
+ })
+
+ // Against fulfilled units, not line items — a return is of something shipped.
+ it('opens a return for fulfilled units', async () => {
+ const result = await client.orders.returns.create(
+ 'or_abc123',
+ {
+ items: [{ fulfillment_item_id: 'fi_1', quantity: 1 }],
+ memo: 'Wrong size',
+ },
+ opts,
+ )
+
+ expect(result.status).toBe('requested')
+ expect(result.number).toMatch(/^RET/)
+ })
+
+ it('works for a guest holding the order token', async () => {
+ const result = await client.orders.returns.list('or_abc123', undefined, {
+ spreeToken: 'guest-token',
+ })
+
+ expect(result.data).toBeDefined()
+ })
+ })
+
+ describe('claims', () => {
+ it('lists claims on an order', async () => {
+ const result = await client.orders.claims.list('or_abc123', undefined, opts)
+
+ expect(result.data).toHaveLength(1)
+ expect(result.data[0].claim_type).toBe('damaged')
+ })
+
+ it('fetches a single claim', async () => {
+ const result = await client.orders.claims.get('or_abc123', 'claim_1', undefined, opts)
+
+ expect(result.id).toBe('claim_1')
+ })
+
+ // Against ordered line items — nothing has to have shipped to report a problem.
+ it('files a claim against ordered items', async () => {
+ const result = await client.orders.claims.create(
+ 'or_abc123',
+ {
+ items: [{ line_item_id: 'li_1', quantity: 1, description: 'Arrived cracked' }],
+ claim_type: 'damaged',
+ },
+ opts,
+ )
+
+ expect(result.status).toBe('open')
+ expect(result.number).toMatch(/^CLM/)
+ })
+ })
+})