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 the exchanges and claims API

Damian Legawiec7898124795b3
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index b2b8f4a3e4..7b4f08be56 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -81,6 +81,9 @@ import type {
CategoryUpdateParams,
ChannelCreateParams,
ChannelUpdateParams,
+ ClaimCreateParams,
+ ClaimResolveParams,
+ ClaimUpdateParams,
CustomerAddressParams,
CustomerCreateParams,
CustomerGroupCreateParams,
@@ -96,6 +99,10 @@ import type {
DeliveryMethodParams,
DeliveryZoneParams,
DirectUploadCreateParams,
+ ExchangeCreateParams,
+ ExchangeFulfillParams,
+ ExchangeReceiveParams,
+ ExchangeUpdateParams,
ExportCreateParams,
FulfillmentCreateParams,
FulfillmentUpdateParams,
@@ -172,6 +179,7 @@ import type {
ApiKey,
Category,
Channel,
+ Claim,
Country,
CouponCode,
CreditCard,
@@ -183,6 +191,7 @@ import type {
DeliveryMethodRule,
DeliveryZone,
Discount,
+ Exchange,
Export,
Fee,
Fulfillment,
@@ -1082,6 +1091,166 @@ export class AdminClient {
}),
},
+ exchanges: {
+ list: (
+ orderId: string,
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<Exchange>> =>
+ this.request<PaginatedResponse<Exchange>>('GET', `/orders/${orderId}/exchanges`, {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (
+ orderId: string,
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<Exchange> =>
+ this.request<Exchange>('GET', `/orders/${orderId}/exchanges/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ create: (
+ orderId: string,
+ params: ExchangeCreateParams,
+ options?: RequestOptions,
+ ): Promise<Exchange> =>
+ this.request<Exchange>('POST', `/orders/${orderId}/exchanges`, {
+ ...options,
+ body: params,
+ }),
+
+ update: (
+ orderId: string,
+ id: string,
+ params: ExchangeUpdateParams,
+ options?: RequestOptions,
+ ): Promise<Exchange> =>
+ this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}`, {
+ ...options,
+ body: params,
+ }),
+
+ approve: (orderId: string, id: string, options?: RequestOptions): Promise<Exchange> =>
+ this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/approve`, options),
+
+ receive: (
+ orderId: string,
+ id: string,
+ params?: ExchangeReceiveParams,
+ options?: RequestOptions,
+ ): Promise<Exchange> =>
+ this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/receive`, {
+ ...options,
+ body: params,
+ }),
+
+ fulfill: (
+ orderId: string,
+ id: string,
+ params?: ExchangeFulfillParams,
+ options?: RequestOptions,
+ ): Promise<Exchange> =>
+ this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/fulfill`, {
+ ...options,
+ body: params,
+ }),
+
+ cancel: (
+ orderId: string,
+ id: string,
+ params?: { reason?: string },
+ options?: RequestOptions,
+ ): Promise<Exchange> =>
+ this.request<Exchange>('PATCH', `/orders/${orderId}/exchanges/${id}/cancel`, {
+ ...options,
+ body: params,
+ }),
+ },
+
+ 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),
+ }),
+
+ create: (
+ orderId: string,
+ params: ClaimCreateParams,
+ options?: RequestOptions,
+ ): Promise<Claim> =>
+ this.request<Claim>('POST', `/orders/${orderId}/claims`, {
+ ...options,
+ body: params,
+ }),
+
+ update: (
+ orderId: string,
+ id: string,
+ params: ClaimUpdateParams,
+ options?: RequestOptions,
+ ): Promise<Claim> =>
+ this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}`, {
+ ...options,
+ body: params,
+ }),
+
+ approve: (orderId: string, id: string, options?: RequestOptions): Promise<Claim> =>
+ this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/approve`, options),
+
+ resolve: (
+ orderId: string,
+ id: string,
+ params: ClaimResolveParams,
+ options?: RequestOptions,
+ ): Promise<Claim> =>
+ this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/resolve`, {
+ ...options,
+ body: params,
+ }),
+
+ deny: (
+ orderId: string,
+ id: string,
+ params?: { reason?: string },
+ options?: RequestOptions,
+ ): Promise<Claim> =>
+ this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/deny`, {
+ ...options,
+ body: params,
+ }),
+
+ cancel: (
+ orderId: string,
+ id: string,
+ params?: { reason?: string },
+ options?: RequestOptions,
+ ): Promise<Claim> =>
+ this.request<Claim>('PATCH', `/orders/${orderId}/claims/${id}/cancel`, {
+ ...options,
+ body: params,
+ }),
+ },
+
payments: {
list: (
orderId: string,
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index a8d2e88eb4..2413c95770 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -159,6 +159,69 @@ export interface ReturnReceiveParams {
}>
}
+export interface ExchangeCreateParams {
+ /** Items coming back, and what should go out in their place */
+ items: Array<{ fulfillment_item_id: string; new_variant_id: string; quantity: number }>
+ stock_location_id?: string
+ reason_id?: string
+ memo?: string
+}
+
+export interface ExchangeUpdateParams {
+ memo?: string
+ reason_id?: string
+ stock_location_id?: string
+ metadata?: Record<string, unknown>
+}
+
+export interface ExchangeReceiveParams {
+ /** Omit to receive everything as requested and resellable */
+ items?: Array<{
+ exchange_line_item_id: string
+ quantity: number
+ resellable?: boolean
+ }>
+}
+
+export interface ExchangeFulfillParams {
+ /**
+ * How a credit is returned when the replacements cost less than what came
+ * back. A balance the customer owes is left for the merchant to collect.
+ */
+ refund_method?: 'original_payment' | 'store_credit'
+}
+
+export interface ClaimCreateParams {
+ /** Affected items, and how each should be made right */
+ items: Array<{
+ line_item_id: string
+ quantity: number
+ description?: string
+ send_replacement?: boolean
+ replacement_variant_id?: string
+ refund_amount?: string | number
+ }>
+ /** One of the store's configured claim types */
+ claim_type?: string
+ reason_id?: string
+ memo?: string
+}
+
+export interface ClaimUpdateParams {
+ memo?: string
+ reason_id?: string
+ claim_type?: string
+ metadata?: Record<string, unknown>
+}
+
+export interface ClaimResolveParams {
+ /** Money back, a replacement shipment, or both */
+ resolution: 'refund' | 'replacement' | 'refund_and_replacement'
+ refund_method?: 'original_payment' | 'store_credit'
+ /** Decimal amount; defaults to the claim total */
+ amount?: string | number
+}
+
export interface ReturnRefundParams {
/**
* Decimal amount; see `PaymentCreateParams.amount` for the string
diff --git a/packages/admin-sdk/src/types/generated/Claim.ts b/packages/admin-sdk/src/types/generated/Claim.ts
new file mode 100644
index 0000000000..44ab730d7b
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/Claim.ts
@@ -0,0 +1,30 @@
+// Typelizer digest 883757aff431909ccc71a357a995267d
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {ClaimLineItem, Order, Refund} from '@/types'
+
+interface Claim {
+ id: string;
+ number: string;
+ status: string;
+ claim_type: string;
+ resolution: string | null;
+ order_id: string | null;
+ reason_id: string | null;
+ refund_total: string;
+ display_refund_total: string;
+ approved_at: string | null;
+ resolved_at: string | null;
+ denied_at: string | null;
+ canceled_at: string | null;
+ claim_line_items?: Array<ClaimLineItem>;
+ memo: string | null;
+ metadata: Record<string, unknown>;
+ created_at: string;
+ updated_at: string;
+ created_by_id: string | null;
+ order?: Order;
+ refunds?: Array<Refund>;
+}
+
+export default Claim;
diff --git a/packages/admin-sdk/src/types/generated/ClaimLineItem.ts b/packages/admin-sdk/src/types/generated/ClaimLineItem.ts
new file mode 100644
index 0000000000..4afc81c6f0
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/ClaimLineItem.ts
@@ -0,0 +1,22 @@
+// Typelizer digest 81b68cced02eb8309f4ad17459cfd240
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {Variant} from '@/types'
+
+interface ClaimLineItem {
+ id: string;
+ quantity: number;
+ send_replacement: boolean;
+ description: string | null;
+ refund_amount: string;
+ display_refund_amount: string;
+ variant_id: string | null;
+ replacement_variant_id: string | null;
+ line_item_id: string | null;
+ variant?: Variant;
+ created_at: string;
+ updated_at: string;
+ replacement_variant?: Variant;
+}
+
+export default ClaimLineItem;
diff --git a/packages/admin-sdk/src/types/generated/Exchange.ts b/packages/admin-sdk/src/types/generated/Exchange.ts
new file mode 100644
index 0000000000..4e1b75b40d
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/Exchange.ts
@@ -0,0 +1,30 @@
+// Typelizer digest aeaa2e01eccac9dbe8ca642b300ea1a3
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {ExchangeLineItem, Order, StockLocation, Refund} from '@/types'
+
+interface Exchange {
+ id: string;
+ number: string;
+ status: string;
+ order_id: string | null;
+ reason_id: string | null;
+ price_difference: string;
+ display_price_difference: string;
+ approved_at: string | null;
+ received_at: string | null;
+ fulfilled_at: string | null;
+ canceled_at: string | null;
+ exchange_line_items?: Array<ExchangeLineItem>;
+ memo: string | null;
+ metadata: Record<string, unknown>;
+ created_at: string;
+ updated_at: string;
+ stock_location_id: string | null;
+ created_by_id: string | null;
+ order?: Order;
+ stock_location?: StockLocation;
+ refunds?: Array<Refund>;
+}
+
+export default Exchange;
diff --git a/packages/admin-sdk/src/types/generated/ExchangeLineItem.ts b/packages/admin-sdk/src/types/generated/ExchangeLineItem.ts
new file mode 100644
index 0000000000..4cd5f5d1ea
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/ExchangeLineItem.ts
@@ -0,0 +1,24 @@
+// Typelizer digest f35738b80d461d5be5f3a72f104ee518
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {Variant} from '@/types'
+
+interface ExchangeLineItem {
+ id: string;
+ quantity: number;
+ received_quantity: number;
+ resellable: boolean;
+ original_price: string;
+ new_variant_price: string;
+ price_difference: string;
+ original_variant_id: string | null;
+ new_variant_id: string | null;
+ line_item_id: string | null;
+ fulfillment_item_id: string | null;
+ original_variant?: Variant;
+ new_variant?: Variant;
+ created_at: string;
+ updated_at: string;
+}
+
+export default ExchangeLineItem;
diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.ts
index 6e974bfefd..8fc3087c29 100644
--- a/packages/admin-sdk/src/types/generated/index.ts
+++ b/packages/admin-sdk/src/types/generated/index.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 2e8a907e16fdd517df4f33e46b0cb869
+// Typelizer digest 9ccdadcbe7896acce65607dfb45d6e6f
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
@@ -9,6 +9,8 @@ export type { default as AppliedPromotion } from './AppliedPromotion'
export type { default as Cart } from './Cart'
export type { default as Category } from './Category'
export type { default as Channel } from './Channel'
+export type { default as ClaimLineItem } from './ClaimLineItem'
+export type { default as Claim } from './Claim'
export type { default as CollectionRule } from './CollectionRule'
export type { default as Collection } from './Collection'
export type { default as Country } from './Country'
@@ -25,6 +27,8 @@ export type { default as DeliveryZoneMember } from './DeliveryZoneMember'
export type { default as DeliveryZone } from './DeliveryZone'
export type { default as DigitalLink } from './DigitalLink'
export type { default as Discount } from './Discount'
+export type { default as ExchangeLineItem } from './ExchangeLineItem'
+export type { default as Exchange } from './Exchange'
export type { default as Export } from './Export'
export type { default as Fee } from './Fee'
export type { default as Fulfillment } from './Fulfillment'
diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.ts
index 36ed1159e8..8cd33f9349 100644
--- a/packages/admin-sdk/src/types/index.ts
+++ b/packages/admin-sdk/src/types/index.ts
@@ -17,6 +17,8 @@ export type { default as ApiKey } from './generated/ApiKey'
export type { default as AppliedPromotion } from './generated/AppliedPromotion'
export type { default as Category } from './generated/Category'
export type { default as Channel } from './generated/Channel'
+export type { default as Claim } from './generated/Claim'
+export type { default as ClaimLineItem } from './generated/ClaimLineItem'
export type { default as Country } from './generated/Country'
export type { default as CouponCode } from './generated/CouponCode'
export type { default as CreditCard } from './generated/CreditCard'
@@ -31,6 +33,8 @@ export type { default as DeliveryZone } from './generated/DeliveryZone'
export type { default as DeliveryZoneMember } from './generated/DeliveryZoneMember'
export type { default as DigitalLink } from './generated/DigitalLink'
export type { default as Discount } from './generated/Discount'
+export type { default as Exchange } from './generated/Exchange'
+export type { default as ExchangeLineItem } from './generated/ExchangeLineItem'
export type { default as Export } from './generated/Export'
export type { default as Fee } from './generated/Fee'
export type { default as Fulfillment } from './generated/Fulfillment'
diff --git a/packages/sdk/src/types/generated/Claim.ts b/packages/sdk/src/types/generated/Claim.ts
new file mode 100644
index 0000000000..88bbf59343
--- /dev/null
+++ b/packages/sdk/src/types/generated/Claim.ts
@@ -0,0 +1,23 @@
+// Typelizer digest c4b21e9aaca07827a9b8288e19911379
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {ClaimLineItem} from '@/types'
+
+interface Claim {
+ id: string;
+ number: string;
+ status: string;
+ claim_type: string;
+ resolution: string | null;
+ order_id: string | null;
+ reason_id: string | null;
+ refund_total: string;
+ display_refund_total: string;
+ approved_at: string | null;
+ resolved_at: string | null;
+ denied_at: string | null;
+ canceled_at: string | null;
+ claim_line_items?: Array<ClaimLineItem>;
+}
+
+export default Claim;
diff --git a/packages/sdk/src/types/generated/ClaimLineItem.ts b/packages/sdk/src/types/generated/ClaimLineItem.ts
new file mode 100644
index 0000000000..78a876b852
--- /dev/null
+++ b/packages/sdk/src/types/generated/ClaimLineItem.ts
@@ -0,0 +1,19 @@
+// Typelizer digest dd52086ce2dae45c2ac6b13cb7e055cd
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {Variant} from '@/types'
+
+interface ClaimLineItem {
+ id: string;
+ quantity: number;
+ send_replacement: boolean;
+ description: string | null;
+ refund_amount: string;
+ display_refund_amount: string;
+ variant_id: string | null;
+ replacement_variant_id: string | null;
+ line_item_id: string | null;
+ variant?: Variant;
+}
+
+export default ClaimLineItem;
diff --git a/packages/sdk/src/types/generated/Exchange.ts b/packages/sdk/src/types/generated/Exchange.ts
new file mode 100644
index 0000000000..99b04cf5bc
--- /dev/null
+++ b/packages/sdk/src/types/generated/Exchange.ts
@@ -0,0 +1,21 @@
+// Typelizer digest 3798e992f1786dd096ec8b93dc9ca3cc
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {ExchangeLineItem} from '@/types'
+
+interface Exchange {
+ id: string;
+ number: string;
+ status: string;
+ order_id: string | null;
+ reason_id: string | null;
+ price_difference: string;
+ display_price_difference: string;
+ approved_at: string | null;
+ received_at: string | null;
+ fulfilled_at: string | null;
+ canceled_at: string | null;
+ exchange_line_items?: Array<ExchangeLineItem>;
+}
+
+export default Exchange;
diff --git a/packages/sdk/src/types/generated/ExchangeLineItem.ts b/packages/sdk/src/types/generated/ExchangeLineItem.ts
new file mode 100644
index 0000000000..32d1dceaeb
--- /dev/null
+++ b/packages/sdk/src/types/generated/ExchangeLineItem.ts
@@ -0,0 +1,22 @@
+// Typelizer digest 6230936c0a851435292a2454ad40dd94
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {Variant} from '@/types'
+
+interface ExchangeLineItem {
+ id: string;
+ quantity: number;
+ received_quantity: number;
+ resellable: boolean;
+ original_price: string;
+ new_variant_price: string;
+ price_difference: string;
+ original_variant_id: string | null;
+ new_variant_id: string | null;
+ line_item_id: string | null;
+ fulfillment_item_id: string | null;
+ original_variant?: Variant;
+ new_variant?: Variant;
+}
+
+export default ExchangeLineItem;
diff --git a/packages/sdk/src/types/generated/index.ts b/packages/sdk/src/types/generated/index.ts
index 4d046605f6..b82b6fa089 100644
--- a/packages/sdk/src/types/generated/index.ts
+++ b/packages/sdk/src/types/generated/index.ts
@@ -1,4 +1,4 @@
-// Typelizer digest c66f7e2d8cd71e566fa7ec43dfe5a7ba
+// Typelizer digest 3a9d9f32d1a94d563b5c4c2b272da5d7
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
@@ -7,6 +7,8 @@ export type { default as Base } from './Base'
export type { default as Cart } from './Cart'
export type { default as Category } from './Category'
export type { default as Channel } from './Channel'
+export type { default as ClaimLineItem } from './ClaimLineItem'
+export type { default as Claim } from './Claim'
export type { default as Collection } from './Collection'
export type { default as Country } from './Country'
export type { default as CreditCard } from './CreditCard'
@@ -21,6 +23,8 @@ export type { default as DeliveryZone } from './DeliveryZone'
export type { default as DigitalLink } from './DigitalLink'
export type { default as Digital } from './Digital'
export type { default as Discount } from './Discount'
+export type { default as ExchangeLineItem } from './ExchangeLineItem'
+export type { default as Exchange } from './Exchange'
export type { default as Fee } from './Fee'
export type { default as Fulfillment } from './Fulfillment'
export type { default as GiftCardBatch } from './GiftCardBatch'
diff --git a/packages/sdk/src/zod/generated/Claim.ts b/packages/sdk/src/zod/generated/Claim.ts
new file mode 100644
index 0000000000..f5a98bacd4
--- /dev/null
+++ b/packages/sdk/src/zod/generated/Claim.ts
@@ -0,0 +1,22 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+import { ClaimLineItemSchema } from './ClaimLineItem';
+
+export const ClaimSchema = z.object({
+ id: z.string(),
+ number: z.string(),
+ status: z.string(),
+ claim_type: z.string(),
+ resolution: z.string().nullable(),
+ order_id: z.string().nullable(),
+ reason_id: z.string().nullable(),
+ refund_total: z.string(),
+ display_refund_total: z.string(),
+ approved_at: z.string().nullable(),
+ resolved_at: z.string().nullable(),
+ denied_at: z.string().nullable(),
+ canceled_at: z.string().nullable(),
+ claim_line_items: z.array(ClaimLineItemSchema).optional(),
+});
+
+export type Claim = z.infer<typeof ClaimSchema>;
diff --git a/packages/sdk/src/zod/generated/ClaimLineItem.ts b/packages/sdk/src/zod/generated/ClaimLineItem.ts
new file mode 100644
index 0000000000..b3cdac158a
--- /dev/null
+++ b/packages/sdk/src/zod/generated/ClaimLineItem.ts
@@ -0,0 +1,18 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+import { VariantSchema } from './Variant';
+
+export const ClaimLineItemSchema = z.object({
+ id: z.string(),
+ quantity: z.number(),
+ send_replacement: z.boolean(),
+ description: z.string().nullable(),
+ refund_amount: z.string(),
+ display_refund_amount: z.string(),
+ variant_id: z.string().nullable(),
+ replacement_variant_id: z.string().nullable(),
+ line_item_id: z.string().nullable(),
+ variant: VariantSchema.optional(),
+});
+
+export type ClaimLineItem = z.infer<typeof ClaimLineItemSchema>;
diff --git a/packages/sdk/src/zod/generated/Exchange.ts b/packages/sdk/src/zod/generated/Exchange.ts
new file mode 100644
index 0000000000..635fa149f8
--- /dev/null
+++ b/packages/sdk/src/zod/generated/Exchange.ts
@@ -0,0 +1,20 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+import { ExchangeLineItemSchema } from './ExchangeLineItem';
+
+export const ExchangeSchema = z.object({
+ id: z.string(),
+ number: z.string(),
+ status: z.string(),
+ order_id: z.string().nullable(),
+ reason_id: z.string().nullable(),
+ price_difference: z.string(),
+ display_price_difference: z.string(),
+ approved_at: z.string().nullable(),
+ received_at: z.string().nullable(),
+ fulfilled_at: z.string().nullable(),
+ canceled_at: z.string().nullable(),
+ exchange_line_items: z.array(ExchangeLineItemSchema).optional(),
+});
+
+export type Exchange = z.infer<typeof ExchangeSchema>;
diff --git a/packages/sdk/src/zod/generated/ExchangeLineItem.ts b/packages/sdk/src/zod/generated/ExchangeLineItem.ts
new file mode 100644
index 0000000000..1303852f8d
--- /dev/null
+++ b/packages/sdk/src/zod/generated/ExchangeLineItem.ts
@@ -0,0 +1,21 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+import { VariantSchema } from './Variant';
+
+export const ExchangeLineItemSchema = z.object({
+ id: z.string(),
+ quantity: z.number(),
+ received_quantity: z.number(),
+ resellable: z.boolean(),
+ original_price: z.string(),
+ new_variant_price: z.string(),
+ price_difference: z.string(),
+ original_variant_id: z.string().nullable(),
+ new_variant_id: z.string().nullable(),
+ line_item_id: z.string().nullable(),
+ fulfillment_item_id: z.string().nullable(),
+ original_variant: VariantSchema.optional(),
+ new_variant: VariantSchema.optional(),
+});
+
+export type ExchangeLineItem = z.infer<typeof ExchangeLineItemSchema>;
diff --git a/packages/sdk/src/zod/generated/index.ts b/packages/sdk/src/zod/generated/index.ts
index f1dd02119e..df5dada59a 100644
--- a/packages/sdk/src/zod/generated/index.ts
+++ b/packages/sdk/src/zod/generated/index.ts
@@ -5,6 +5,8 @@ export { BaseSchema, type Base } from './Base';
export { CartSchema, type Cart } from './Cart';
export { CategorySchema, type Category } from './Category';
export { ChannelSchema, type Channel } from './Channel';
+export { ClaimSchema, type Claim } from './Claim';
+export { ClaimLineItemSchema, type ClaimLineItem } from './ClaimLineItem';
export { CollectionSchema, type Collection } from './Collection';
export { CountrySchema, type Country } from './Country';
export { CreditCardSchema, type CreditCard } from './CreditCard';
@@ -19,6 +21,8 @@ export { DeliveryZoneMemberSchema, type DeliveryZoneMember } from './DeliveryZon
export { DigitalSchema, type Digital } from './Digital';
export { DigitalLinkSchema, type DigitalLink } from './DigitalLink';
export { DiscountSchema, type Discount } from './Discount';
+export { ExchangeSchema, type Exchange } from './Exchange';
+export { ExchangeLineItemSchema, type ExchangeLineItem } from './ExchangeLineItem';
export { FeeSchema, type Fee } from './Fee';
export { FulfillmentSchema, type Fulfillment } from './Fulfillment';
export { GiftCardSchema, type GiftCard } from './GiftCard';
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/claims_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/claims_controller.rb
new file mode 100644
index 0000000000..1fdec6e789
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/claims_controller.rb
@@ -0,0 +1,140 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ module Orders
+ # Claims on a completed order.
+ class ClaimsController < BaseController
+ scoped_resource :claims
+
+ before_action :set_resource, only: [:show, :update, :approve, :resolve, :deny, :cancel]
+
+ # POST /api/v3/admin/orders/:order_id/claims
+ def create
+ authorize!(:create, Spree::Claim)
+
+ result = Spree.claim_create_workflow.call(
+ order: @order,
+ items: items_for_create,
+ claim_type: create_params[:claim_type] || 'other',
+ reason: reason_for_create,
+ memo: create_params[:memo],
+ created_by: try_spree_current_user
+ )
+
+ if result.success?
+ render json: serialize_resource(result.value), status: :created
+ else
+ render_result_error(result)
+ end
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/claims/:id
+ def update
+ if @resource.update(permitted_params)
+ render json: serialize_resource(@resource.reload)
+ else
+ render_validation_error(@resource.errors)
+ end
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/claims/:id/approve
+ def approve
+ run_workflow(Spree.claim_approve_workflow, approver: try_spree_current_user)
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/claims/:id/resolve
+ #
+ # The resolution is chosen here rather than at claim creation, so
+ # an admin decides how to make things right once they have the
+ # facts.
+ def resolve
+ run_workflow(Spree.claim_resolve_workflow,
+ resolution: params[:resolution],
+ refund_method: params[:refund_method] || 'store_credit',
+ amount: params[:amount],
+ resolver: try_spree_current_user)
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/claims/:id/deny
+ def deny
+ run_workflow(Spree.claim_deny_workflow, reason: params[:reason])
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/claims/:id/cancel
+ def cancel
+ run_workflow(Spree.claim_cancel_workflow, reason: params[:reason])
+ end
+
+ protected
+
+ def model_class
+ Spree::Claim
+ end
+
+ def serializer_class
+ Spree.api.admin_claim_serializer
+ end
+
+ def parent_association
+ :claims
+ end
+
+ def collection_includes
+ [:reason, { claim_line_items: [:variant, :replacement_variant] }]
+ end
+
+ def permitted_params
+ params.permit(:memo, :reason_id, :claim_type, metadata: {})
+ end
+
+ def create_params
+ @create_params ||= params.permit(
+ :memo, :reason_id, :claim_type,
+ items: [:line_item_id, :quantity, :description, :send_replacement,
+ :replacement_variant_id, :refund_amount]
+ )
+ end
+
+ private
+
+ def run_workflow(workflow, **arguments)
+ result = workflow.call(claim: @resource, **arguments)
+
+ if result.success?
+ render json: serialize_resource(result.value)
+ else
+ render_result_error(result)
+ end
+ end
+
+ def items_for_create
+ Array(create_params[:items]).map do |item|
+ {
+ line_item: @order.line_items.find_by_prefix_id!(item[:line_item_id]),
+ quantity: item[:quantity].to_i,
+ description: item[:description],
+ send_replacement: ActiveModel::Type::Boolean.new.cast(item[:send_replacement]),
+ replacement_variant: replacement_variant_for(item),
+ refund_amount: item[:refund_amount]
+ }
+ end
+ end
+
+ def replacement_variant_for(item)
+ return nil if item[:replacement_variant_id].blank?
+
+ current_store.variants.find_by_prefix_id!(item[:replacement_variant_id])
+ end
+
+ def reason_for_create
+ return nil if create_params[:reason_id].blank?
+
+ Spree::ReturnAuthorizationReason.find_by_prefix_id!(create_params[:reason_id])
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/exchanges_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/exchanges_controller.rb
new file mode 100644
index 0000000000..54ef250b96
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/exchanges_controller.rb
@@ -0,0 +1,144 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ module Orders
+ # Exchanges on a completed order. Each status change is its own
+ # member action, because each carries different arguments.
+ class ExchangesController < BaseController
+ scoped_resource :exchanges
+
+ before_action :set_resource, only: [:show, :update, :approve, :receive, :fulfill, :cancel]
+
+ # POST /api/v3/admin/orders/:order_id/exchanges
+ def create
+ authorize!(:create, Spree::Exchange)
+
+ result = Spree.exchange_create_workflow.call(
+ order: @order,
+ items: items_for_create,
+ stock_location: stock_location_for_create,
+ reason: reason_for_create,
+ memo: create_params[:memo],
+ created_by: try_spree_current_user
+ )
+
+ if result.success?
+ render json: serialize_resource(result.value), status: :created
+ else
+ render_result_error(result)
+ end
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/exchanges/:id
+ def update
+ if @resource.update(permitted_params)
+ render json: serialize_resource(@resource.reload)
+ else
+ render_validation_error(@resource.errors)
+ end
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/exchanges/:id/approve
+ def approve
+ run_workflow(Spree.exchange_approve_workflow, approver: try_spree_current_user)
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/exchanges/:id/receive
+ def receive
+ run_workflow(Spree.exchange_receive_workflow,
+ items: items_for_receive,
+ received_by: try_spree_current_user)
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/exchanges/:id/fulfill
+ def fulfill
+ run_workflow(Spree.exchange_fulfill_workflow,
+ refund_method: params[:refund_method] || 'store_credit',
+ refunder: try_spree_current_user)
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/exchanges/:id/cancel
+ def cancel
+ run_workflow(Spree.exchange_cancel_workflow, reason: params[:reason])
+ end
+
+ protected
+
+ def model_class
+ Spree::Exchange
+ end
+
+ def serializer_class
+ Spree.api.admin_exchange_serializer
+ end
+
+ def parent_association
+ :exchanges
+ end
+
+ def collection_includes
+ [:reason, :stock_location, { exchange_line_items: [:original_variant, :new_variant] }]
+ end
+
+ def permitted_params
+ params.permit(:memo, :reason_id, :stock_location_id, metadata: {})
+ end
+
+ def create_params
+ @create_params ||= params.permit(:memo, :reason_id, :stock_location_id,
+ items: [:fulfillment_item_id, :new_variant_id, :quantity])
+ end
+
+ private
+
+ def run_workflow(workflow, **arguments)
+ result = workflow.call(exchange: @resource, **arguments)
+
+ if result.success?
+ render json: serialize_resource(result.value)
+ else
+ render_result_error(result)
+ end
+ end
+
+ def items_for_create
+ Array(create_params[:items]).map do |item|
+ {
+ fulfillment_item: @order.fulfillment_items.find_by_prefix_id!(item[:fulfillment_item_id]),
+ new_variant: current_store.variants.find_by_prefix_id!(item[:new_variant_id]),
+ quantity: item[:quantity].to_i
+ }
+ end
+ end
+
+ def items_for_receive
+ return nil if params[:items].blank?
+
+ params.permit(items: [:exchange_line_item_id, :quantity, :resellable])[:items].map do |item|
+ {
+ exchange_line_item: @resource.exchange_line_items.find_by_prefix_id!(item[:exchange_line_item_id]),
+ quantity: item[:quantity].to_i,
+ resellable: item.key?(:resellable) ? ActiveModel::Type::Boolean.new.cast(item[:resellable]) : true
+ }
+ end
+ end
+
+ def stock_location_for_create
+ return nil if create_params[:stock_location_id].blank?
+
+ Spree::StockLocation.accessible_by(current_ability, :show).
+ find_by_prefix_id!(create_params[:stock_location_id])
+ end
+
+ def reason_for_create
+ return nil if create_params[:reason_id].blank?
+
+ Spree::ReturnAuthorizationReason.find_by_prefix_id!(create_params[:reason_id])
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/store/orders/claims_controller.rb b/spree/api/app/controllers/spree/api/v3/store/orders/claims_controller.rb
new file mode 100644
index 0000000000..c1ff8bdd38
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/store/orders/claims_controller.rb
@@ -0,0 +1,95 @@
+module Spree
+ module Api
+ module V3
+ module Store
+ module Orders
+ # Customer self-service claims — reporting a damaged, missing or
+ # wrong item. Approving, denying and resolving are the merchant's,
+ # through the Admin API.
+ #
+ # Whether a customer may file a claim is store policy and belongs in
+ # a `claims.create.validate` hook rather than here.
+ class ClaimsController < Store::ResourceController
+ def create
+ result = Spree.claim_create_workflow.call(
+ order: @parent,
+ items: items_for_create,
+ claim_type: create_params[:claim_type] || 'other',
+ memo: create_params[:memo]
+ )
+
+ if result.success?
+ render json: serialize_resource(result.value), status: :created
+ else
+ render_result_error(result)
+ end
+ end
+
+ protected
+
+ def model_class
+ Spree::Claim
+ end
+
+ def serializer_class
+ Spree.api.claim_serializer
+ end
+
+ def scope
+ @parent.claims.order(created_at: :desc)
+ end
+
+ def collection_includes
+ [{ claim_line_items: :variant }]
+ end
+
+ def set_parent
+ cart_pk = Spree::Cart.decode_own_prefixed_id(params[:order_id])
+ @parent = if cart_pk
+ order_scope.find_by!(cart_id: cart_pk)
+ else
+ order_scope.find_by_prefix_id!(params[:order_id])
+ end
+ authorize!(:show, @parent, order_token)
+ end
+
+ # Authorization is the parent order's — see the returns
+ # controller for why a second record-level check is wrong here.
+ def set_resource
+ @resource = find_resource
+ end
+
+ def order_scope
+ base = current_store.orders.complete
+
+ if current_user.present?
+ base.where(user: current_user)
+ elsif order_token.present?
+ base.where(token: order_token)
+ else
+ base.none
+ end
+ end
+
+ def create_params
+ @create_params ||= params.permit(:memo, :claim_type,
+ items: [:line_item_id, :quantity, :description])
+ end
+
+ private
+
+ def items_for_create
+ Array(create_params[:items]).map do |item|
+ {
+ line_item: @parent.line_items.find_by_prefix_id!(item[:line_item_id]),
+ quantity: item[:quantity].to_i,
+ description: item[:description]
+ }
+ end
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/claim_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/claim_line_item_serializer.rb
new file mode 100644
index 0000000000..1142282443
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/claim_line_item_serializer.rb
@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ module Admin
+ class ClaimLineItemSerializer < V3::ClaimLineItemSerializer
+ attributes created_at: :iso8601, updated_at: :iso8601
+
+ one :variant, resource: proc { Spree.api.admin_variant_serializer }, if: proc { expand?('variant') }
+ one :replacement_variant, resource: proc { Spree.api.admin_variant_serializer }, if: proc { expand?('replacement_variant') }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/claim_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/claim_serializer.rb
new file mode 100644
index 0000000000..73ae78f843
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/claim_serializer.rb
@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ module Admin
+ class ClaimSerializer < V3::ClaimSerializer
+ typelize memo: [:string, nullable: true],
+ metadata: 'Record<string, unknown>',
+ created_by_id: [:string, nullable: true]
+
+ attributes :memo, :metadata, created_at: :iso8601, updated_at: :iso8601
+
+ attribute :created_by_id do |claim|
+ claim.created_by&.prefixed_id
+ end
+
+ many :claim_line_items,
+ resource: proc { Spree.api.admin_claim_line_item_serializer },
+ if: proc { expand?('claim_line_items') }
+
+ one :order, resource: proc { Spree.api.admin_order_serializer }, if: proc { expand?('order') }
+ many :refunds, resource: proc { Spree.api.admin_refund_serializer }, if: proc { expand?('refunds') }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/exchange_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/exchange_line_item_serializer.rb
new file mode 100644
index 0000000000..20295621de
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/exchange_line_item_serializer.rb
@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ module Admin
+ class ExchangeLineItemSerializer < V3::ExchangeLineItemSerializer
+ attributes created_at: :iso8601, updated_at: :iso8601
+
+ one :original_variant, resource: proc { Spree.api.admin_variant_serializer }, if: proc { expand?('original_variant') }
+ one :new_variant, resource: proc { Spree.api.admin_variant_serializer }, if: proc { expand?('new_variant') }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/exchange_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/exchange_serializer.rb
new file mode 100644
index 0000000000..4c15e4b260
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/exchange_serializer.rb
@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ module Admin
+ class ExchangeSerializer < V3::ExchangeSerializer
+ typelize memo: [:string, nullable: true],
+ metadata: 'Record<string, unknown>',
+ stock_location_id: [:string, nullable: true],
+ created_by_id: [:string, nullable: true]
+
+ attributes :memo, :metadata, created_at: :iso8601, updated_at: :iso8601
+
+ attribute :stock_location_id do |exchange|
+ exchange.stock_location&.prefixed_id
+ end
+
+ attribute :created_by_id do |exchange|
+ exchange.created_by&.prefixed_id
+ end
+
+ many :exchange_line_items,
+ resource: proc { Spree.api.admin_exchange_line_item_serializer },
+ if: proc { expand?('exchange_line_items') }
+
+ one :order, resource: proc { Spree.api.admin_order_serializer }, if: proc { expand?('order') }
+ one :stock_location, resource: proc { Spree.api.admin_stock_location_serializer }, if: proc { expand?('stock_location') }
+ many :refunds, resource: proc { Spree.api.admin_refund_serializer }, if: proc { expand?('refunds') }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/claim_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/claim_line_item_serializer.rb
new file mode 100644
index 0000000000..44a56195ea
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/claim_line_item_serializer.rb
@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ class ClaimLineItemSerializer < BaseSerializer
+ typelize quantity: :number,
+ send_replacement: :boolean,
+ refund_amount: :string,
+ display_refund_amount: :string,
+ description: [:string, nullable: true],
+ variant_id: [:string, nullable: true],
+ replacement_variant_id: [:string, nullable: true],
+ line_item_id: [:string, nullable: true]
+
+ attributes :quantity, :send_replacement, :description
+
+ attribute :refund_amount do |line|
+ line.refund_amount.to_s
+ end
+
+ attribute :display_refund_amount do |line|
+ line.display_refund_amount.to_s
+ end
+
+ attribute :variant_id do |line|
+ line.variant&.prefixed_id
+ end
+
+ attribute :replacement_variant_id do |line|
+ line.replacement_variant&.prefixed_id
+ end
+
+ attribute :line_item_id do |line|
+ line.line_item&.prefixed_id
+ end
+
+ one :variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('variant') }
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/claim_serializer.rb b/spree/api/app/serializers/spree/api/v3/claim_serializer.rb
new file mode 100644
index 0000000000..eafd580826
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/claim_serializer.rb
@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ # Customer-facing view of a claim.
+ class ClaimSerializer < BaseSerializer
+ typelize number: :string,
+ status: :string,
+ claim_type: :string,
+ resolution: [:string, nullable: true],
+ order_id: [:string, nullable: true],
+ reason_id: [:string, nullable: true],
+ refund_total: :string,
+ display_refund_total: :string,
+ approved_at: [:string, nullable: true],
+ resolved_at: [:string, nullable: true],
+ denied_at: [:string, nullable: true],
+ canceled_at: [:string, nullable: true]
+
+ attributes :number, :status, :claim_type, :resolution
+
+ attribute :order_id do |claim|
+ claim.order&.prefixed_id
+ end
+
+ attribute :reason_id do |claim|
+ claim.reason&.prefixed_id
+ end
+
+ attribute :refund_total do |claim|
+ claim.refund_total.to_s
+ end
+
+ attribute :display_refund_total do |claim|
+ claim.display_refund_total.to_s
+ end
+
+ attribute :approved_at do |claim|
+ claim.approved_at&.iso8601
+ end
+
+ attribute :resolved_at do |claim|
+ claim.resolved_at&.iso8601
+ end
+
+ attribute :denied_at do |claim|
+ claim.denied_at&.iso8601
+ end
+
+ attribute :canceled_at do |claim|
+ claim.canceled_at&.iso8601
+ end
+
+ many :claim_line_items,
+ resource: proc { Spree.api.claim_line_item_serializer },
+ if: proc { expand?('claim_line_items') }
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/exchange_line_item_serializer.rb b/spree/api/app/serializers/spree/api/v3/exchange_line_item_serializer.rb
new file mode 100644
index 0000000000..6bc7579b56
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/exchange_line_item_serializer.rb
@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ class ExchangeLineItemSerializer < BaseSerializer
+ typelize quantity: :number,
+ received_quantity: :number,
+ resellable: :boolean,
+ original_price: :string,
+ new_variant_price: :string,
+ price_difference: :string,
+ original_variant_id: [:string, nullable: true],
+ new_variant_id: [:string, nullable: true],
+ line_item_id: [:string, nullable: true],
+ fulfillment_item_id: [:string, nullable: true]
+
+ attributes :quantity, :received_quantity, :resellable
+
+ attribute :original_price do |line|
+ line.original_price.to_s
+ end
+
+ attribute :new_variant_price do |line|
+ line.new_variant_price.to_s
+ end
+
+ attribute :price_difference do |line|
+ line.price_difference.to_s
+ end
+
+ attribute :original_variant_id do |line|
+ line.original_variant&.prefixed_id
+ end
+
+ attribute :new_variant_id do |line|
+ line.new_variant&.prefixed_id
+ end
+
+ attribute :line_item_id do |line|
+ line.line_item&.prefixed_id
+ end
+
+ attribute :fulfillment_item_id do |line|
+ line.fulfillment_item&.prefixed_id
+ end
+
+ one :original_variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('original_variant') }
+ one :new_variant, resource: proc { Spree.api.variant_serializer }, if: proc { expand?('new_variant') }
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/exchange_serializer.rb b/spree/api/app/serializers/spree/api/v3/exchange_serializer.rb
new file mode 100644
index 0000000000..0a3d7e6d51
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/exchange_serializer.rb
@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Spree
+ module Api
+ module V3
+ # Customer-facing view of an exchange.
+ class ExchangeSerializer < BaseSerializer
+ typelize number: :string,
+ status: :string,
+ order_id: [:string, nullable: true],
+ reason_id: [:string, nullable: true],
+ price_difference: :string,
+ display_price_difference: :string,
+ approved_at: [:string, nullable: true],
+ received_at: [:string, nullable: true],
+ fulfilled_at: [:string, nullable: true],
+ canceled_at: [:string, nullable: true]
+
+ attributes :number, :status
+
+ attribute :order_id do |exchange|
+ exchange.order&.prefixed_id
+ end
+
+ attribute :reason_id do |exchange|
+ exchange.reason&.prefixed_id
+ end
+
+ attribute :price_difference do |exchange|
+ exchange.price_difference.to_s
+ end
+
+ attribute :display_price_difference do |exchange|
+ exchange.display_price_difference.to_s
+ end
+
+ attribute :approved_at do |exchange|
+ exchange.approved_at&.iso8601
+ end
+
+ attribute :received_at do |exchange|
+ exchange.received_at&.iso8601
+ end
+
+ attribute :fulfilled_at do |exchange|
+ exchange.fulfilled_at&.iso8601
+ end
+
+ attribute :canceled_at do |exchange|
+ exchange.canceled_at&.iso8601
+ end
+
+ many :exchange_line_items,
+ resource: proc { Spree.api.exchange_line_item_serializer },
+ if: proc { expand?('exchange_line_items') }
+ end
+ end
+ end
+end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index bb5410169e..257d8ac678 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -66,6 +66,7 @@ Spree::Core::Engine.add_routes do
# Customer self-service returns — opening and viewing only; the
# merchant approves, receives and refunds through the Admin API.
resources :returns, only: [:index, :show, :create], controller: 'orders/returns'
+ resources :claims, only: [:index, :show, :create], controller: 'orders/claims'
end
# Policies (return policy, privacy policy, terms of service, etc.)
@@ -432,6 +433,22 @@ Spree::Core::Engine.add_routes do
patch :cancel
end
end
+ resources :exchanges, controller: 'orders/exchanges', only: [:index, :show, :create, :update] do
+ member do
+ patch :approve
+ patch :receive
+ patch :fulfill
+ patch :cancel
+ end
+ end
+ resources :claims, controller: 'orders/claims', only: [:index, :show, :create, :update] do
+ member do
+ patch :approve
+ patch :resolve
+ patch :deny
+ patch :cancel
+ end
+ end
resources :payments, controller: 'orders/payments', only: [:index, :show, :create] do
member do
patch :capture
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index e814be6fb0..d67d9bc73c 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -72,6 +72,10 @@ module Spree
customer_return_serializer: 'Spree::Api::V3::CustomerReturnSerializer',
return_serializer: 'Spree::Api::V3::ReturnSerializer',
return_line_item_serializer: 'Spree::Api::V3::ReturnLineItemSerializer',
+ exchange_serializer: 'Spree::Api::V3::ExchangeSerializer',
+ exchange_line_item_serializer: 'Spree::Api::V3::ExchangeLineItemSerializer',
+ claim_serializer: 'Spree::Api::V3::ClaimSerializer',
+ claim_line_item_serializer: 'Spree::Api::V3::ClaimLineItemSerializer',
digital_serializer: 'Spree::Api::V3::DigitalSerializer',
export_serializer: 'Spree::Api::V3::ExportSerializer',
gift_card_batch_serializer: 'Spree::Api::V3::GiftCardBatchSerializer',
@@ -128,6 +132,10 @@ module Spree
admin_refund_serializer: 'Spree::Api::V3::Admin::RefundSerializer',
admin_return_serializer: 'Spree::Api::V3::Admin::ReturnSerializer',
admin_return_line_item_serializer: 'Spree::Api::V3::Admin::ReturnLineItemSerializer',
+ admin_exchange_serializer: 'Spree::Api::V3::Admin::ExchangeSerializer',
+ admin_exchange_line_item_serializer: 'Spree::Api::V3::Admin::ExchangeLineItemSerializer',
+ admin_claim_serializer: 'Spree::Api::V3::Admin::ClaimSerializer',
+ admin_claim_line_item_serializer: 'Spree::Api::V3::Admin::ClaimLineItemSerializer',
admin_shipping_category_serializer: 'Spree::Api::V3::Admin::ShippingCategorySerializer',
admin_tax_category_serializer: 'Spree::Api::V3::Admin::TaxCategorySerializer',
admin_return_authorization_serializer: 'Spree::Api::V3::Admin::ReturnAuthorizationSerializer',
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/claims_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/claims_controller_spec.rb
new file mode 100644
index 0000000000..ed17bdfa6e
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/claims_controller_spec.rb
@@ -0,0 +1,92 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::Orders::ClaimsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:order) { create(:shipped_order, store: store, line_items_count: 2) }
+ let(:line_item) { order.line_items.first }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'POST #create' do
+ it 'opens a claim' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ claim_type: 'damaged',
+ memo: 'Arrived cracked',
+ items: [{ line_item_id: line_item.prefixed_id, quantity: 1, description: 'Cracked screen' }]
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['status']).to eq('open')
+ expect(json_response['claim_type']).to eq('damaged')
+ expect(json_response['number']).to start_with('CLM')
+ end
+
+ it 'rejects an unknown claim type' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ claim_type: 'teleported',
+ items: [{ line_item_id: line_item.prefixed_id, quantity: 1 }]
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ describe 'PATCH #approve' do
+ it 'approves an open claim' do
+ claim = create(:claim, store: store, order: order)
+
+ patch :approve, params: { order_id: order.prefixed_id, id: claim.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['status']).to eq('approved')
+ end
+ end
+
+ describe 'PATCH #resolve' do
+ let(:claim) { create(:approved_claim, store: store, order: order) }
+
+ it 'resolves with a store credit refund' do
+ patch :resolve, params: {
+ order_id: order.prefixed_id,
+ id: claim.prefixed_id,
+ resolution: 'refund',
+ refund_method: 'store_credit'
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['status']).to eq('resolved')
+ expect(json_response['resolution']).to eq('refund')
+ expect(Spree::StoreCredit.find_by(originator: claim)).to be_present
+ end
+
+ it 'rejects an unknown resolution' do
+ patch :resolve, params: {
+ order_id: order.prefixed_id,
+ id: claim.prefixed_id,
+ resolution: 'apologize'
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ describe 'PATCH #deny' do
+ it 'denies an open claim with a reason' do
+ claim = create(:claim, store: store, order: order)
+
+ patch :deny, params: {
+ order_id: order.prefixed_id,
+ id: claim.prefixed_id,
+ reason: 'Outside warranty'
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['status']).to eq('denied')
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/exchanges_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/exchanges_controller_spec.rb
new file mode 100644
index 0000000000..9e719b68d8
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/exchanges_controller_spec.rb
@@ -0,0 +1,92 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::Orders::ExchangesController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:order) { create(:shipped_order, store: store, line_items_count: 2) }
+ let(:fulfillment_item) { order.fulfillment_items.first }
+ let(:replacement) { create(:variant, product: fulfillment_item.variant.product) }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'POST #create' do
+ it 'opens an exchange' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ memo: 'Wrong size',
+ items: [{
+ fulfillment_item_id: fulfillment_item.prefixed_id,
+ new_variant_id: replacement.prefixed_id,
+ quantity: 1
+ }]
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['status']).to eq('requested')
+ expect(json_response['number']).to start_with('EX')
+ end
+
+ it 'rejects exchanging an item for itself' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ items: [{
+ fulfillment_item_id: fulfillment_item.prefixed_id,
+ new_variant_id: fulfillment_item.variant.prefixed_id,
+ quantity: 1
+ }]
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ describe 'GET #index' do
+ it 'lists exchanges on the order' do
+ create(:exchange, store: store, order: order)
+
+ get :index, params: { order_id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].length).to eq(1)
+ end
+ end
+
+ describe 'PATCH #approve' do
+ it 'approves a requested exchange' do
+ exchange = create(:exchange, store: store, order: order)
+
+ patch :approve, params: { order_id: order.prefixed_id, id: exchange.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['status']).to eq('approved')
+ end
+ end
+
+ describe 'PATCH #receive' do
+ it 'records a partial receipt' do
+ exchange = create(:approved_exchange, store: store, order: order)
+ line = exchange.exchange_line_items.first
+
+ patch :receive, params: {
+ order_id: order.prefixed_id,
+ id: exchange.prefixed_id,
+ items: [{ exchange_line_item_id: line.prefixed_id, quantity: 1, resellable: false }]
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(line.reload.resellable).to be(false)
+ end
+ end
+
+ describe 'PATCH #cancel' do
+ it 'refuses an exchange already received' do
+ exchange = create(:received_exchange, store: store, order: order)
+
+ patch :cancel, params: { order_id: order.prefixed_id, id: exchange.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+end
diff --git a/spree/core/app/workflows/spree/claims/create.rb b/spree/core/app/workflows/spree/claims/create.rb
index e3d447acc2..93823d33df 100644
--- a/spree/core/app/workflows/spree/claims/create.rb
+++ b/spree/core/app/workflows/spree/claims/create.rb
@@ -70,7 +70,9 @@ module Spree
variant: item[:line_item].variant,
quantity: item[:quantity],
description: item[:description],
- send_replacement: item.fetch(:send_replacement, false),
+ # A caller that omits this — or passes nil for an absent param —
+ # must not write NULL over the column default.
+ send_replacement: ActiveModel::Type::Boolean.new.cast(item[:send_replacement]) || false,
replacement_variant: item[:replacement_variant],
refund_amount: item[:refund_amount] || 0
)