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.

Admin API: Order nested resources — shipments, payments, refunds, adjustments

Damian Legawieccd514314deab
diff --git a/packages/sdk/src/admin-client.ts b/packages/sdk/src/admin-client.ts
index d53c265a0e..e588962a49 100644
--- a/packages/sdk/src/admin-client.ts
+++ b/packages/sdk/src/admin-client.ts
@@ -6,16 +6,22 @@ import { transformListParams } from './params';
import type {
PaginatedResponse,
ListParams,
+ AdminAdjustment,
AdminAsset,
AdminLineItem,
AdminOptionType,
AdminOrder,
+ AdminPayment,
AdminProduct,
+ AdminRefund,
+ AdminShipment,
AdminTaxon,
AdminTaxonomy,
AdminVariant,
} from './types';
import type {
+ AdminAdjustmentCreateParams,
+ AdminAdjustmentUpdateParams,
AdminAssetCreateParams,
AdminAssetUpdateParams,
AdminLineItemCreateParams,
@@ -24,8 +30,11 @@ import type {
AdminOptionTypeUpdateParams,
AdminOrderCreateParams,
AdminOrderUpdateParams,
+ AdminPaymentCreateParams,
AdminProductCreateParams,
AdminProductUpdateParams,
+ AdminRefundCreateParams,
+ AdminShipmentUpdateParams,
AdminTaxonCreateParams,
AdminTaxonUpdateParams,
AdminTaxonomyCreateParams,
@@ -35,6 +44,8 @@ import type {
} from './admin-params';
export type {
+ AdminAdjustmentCreateParams,
+ AdminAdjustmentUpdateParams,
AdminAssetCreateParams,
AdminAssetUpdateParams,
AdminLineItemCreateParams,
@@ -43,8 +54,11 @@ export type {
AdminOptionTypeUpdateParams,
AdminOrderCreateParams,
AdminOrderUpdateParams,
+ AdminPaymentCreateParams,
AdminProductCreateParams,
AdminProductUpdateParams,
+ AdminRefundCreateParams,
+ AdminShipmentUpdateParams,
AdminTaxonCreateParams,
AdminTaxonUpdateParams,
AdminTaxonomyCreateParams,
@@ -278,6 +292,191 @@ export class AdminClient {
},
+ /** Nested: orders/{id}/shipments */
+ shipments: {
+ /** List shipments */
+ list: (
+ orderId: string,
+ params?: ListParams,
+ options?: RequestOptions
+ ): Promise<PaginatedResponse<AdminShipment>> =>
+ this.request<PaginatedResponse<AdminShipment>>('GET', `/orders/${orderId}/shipments`, {
+ ...options,
+ params: transformListParams({ ...params }),
+ }),
+
+ /** Show a shipment */
+ get: (
+ orderId: string,
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions
+ ): Promise<AdminShipment> =>
+ this.request<AdminShipment>('GET', `/orders/${orderId}/shipments/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ /** Update a shipment */
+ update: (
+ orderId: string,
+ id: string,
+ params: AdminShipmentUpdateParams,
+ options?: RequestOptions
+ ): Promise<AdminShipment> =>
+ this.request<AdminShipment>('PATCH', `/orders/${orderId}/shipments/${id}`, {
+ ...options,
+ body: params,
+ }),
+
+ /** Ship a shipment */
+ ship: (
+ orderId: string,
+ id: string,
+ options?: RequestOptions
+ ): Promise<AdminShipment> =>
+ this.request<AdminShipment>('PATCH', `/orders/${orderId}/shipments/${id}/ship`, options),
+
+ },
+
+ /** Nested: orders/{id}/payments */
+ payments: {
+ /** List payments */
+ list: (
+ orderId: string,
+ params?: ListParams,
+ options?: RequestOptions
+ ): Promise<PaginatedResponse<AdminPayment>> =>
+ this.request<PaginatedResponse<AdminPayment>>('GET', `/orders/${orderId}/payments`, {
+ ...options,
+ params: transformListParams({ ...params }),
+ }),
+
+ /** Show a payment */
+ get: (
+ orderId: string,
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions
+ ): Promise<AdminPayment> =>
+ this.request<AdminPayment>('GET', `/orders/${orderId}/payments/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ /** Create a payment */
+ create: (
+ orderId: string,
+ params: AdminPaymentCreateParams,
+ options?: RequestOptions
+ ): Promise<AdminPayment> =>
+ this.request<AdminPayment>('POST', `/orders/${orderId}/payments`, {
+ ...options,
+ body: params,
+ }),
+
+ /** Capture a payment */
+ capture: (
+ orderId: string,
+ id: string,
+ options?: RequestOptions
+ ): Promise<AdminPayment> =>
+ this.request<AdminPayment>('PATCH', `/orders/${orderId}/payments/${id}/capture`, options),
+
+ /** Void a payment */
+ void: (
+ orderId: string,
+ id: string,
+ options?: RequestOptions
+ ): Promise<AdminPayment> =>
+ this.request<AdminPayment>('PATCH', `/orders/${orderId}/payments/${id}/void`, options),
+
+ },
+
+ /** Nested: orders/{id}/refunds */
+ refunds: {
+ /** List refunds */
+ list: (
+ orderId: string,
+ params?: ListParams,
+ options?: RequestOptions
+ ): Promise<PaginatedResponse<AdminRefund>> =>
+ this.request<PaginatedResponse<AdminRefund>>('GET', `/orders/${orderId}/refunds`, {
+ ...options,
+ params: transformListParams({ ...params }),
+ }),
+
+ /** Create a refund */
+ create: (
+ orderId: string,
+ params: AdminRefundCreateParams,
+ options?: RequestOptions
+ ): Promise<AdminRefund> =>
+ this.request<AdminRefund>('POST', `/orders/${orderId}/refunds`, {
+ ...options,
+ body: params,
+ }),
+
+ },
+
+ /** Nested: orders/{id}/adjustments */
+ adjustments: {
+ /** List adjustments */
+ list: (
+ orderId: string,
+ params?: ListParams,
+ options?: RequestOptions
+ ): Promise<PaginatedResponse<AdminAdjustment>> =>
+ this.request<PaginatedResponse<AdminAdjustment>>('GET', `/orders/${orderId}/adjustments`, {
+ ...options,
+ params: transformListParams({ ...params }),
+ }),
+
+ /** Show an adjustment */
+ get: (
+ orderId: string,
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions
+ ): Promise<AdminAdjustment> =>
+ this.request<AdminAdjustment>('GET', `/orders/${orderId}/adjustments/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ /** Create an adjustment */
+ create: (
+ orderId: string,
+ params: AdminAdjustmentCreateParams,
+ options?: RequestOptions
+ ): Promise<AdminAdjustment> =>
+ this.request<AdminAdjustment>('POST', `/orders/${orderId}/adjustments`, {
+ ...options,
+ body: params,
+ }),
+
+ /** Update an adjustment */
+ update: (
+ orderId: string,
+ id: string,
+ params: AdminAdjustmentUpdateParams,
+ options?: RequestOptions
+ ): Promise<AdminAdjustment> =>
+ this.request<AdminAdjustment>('PATCH', `/orders/${orderId}/adjustments/${id}`, {
+ ...options,
+ body: params,
+ }),
+
+ /** Delete an adjustment */
+ delete: (
+ orderId: string,
+ id: string,
+ options?: RequestOptions
+ ): Promise<void> =>
+ this.request<void>('DELETE', `/orders/${orderId}/adjustments/${id}`, options),
+
+ },
+
};
// ============================================
diff --git a/packages/sdk/src/admin-params.ts b/packages/sdk/src/admin-params.ts
index be2e61b021..d2e3e82a00 100644
--- a/packages/sdk/src/admin-params.ts
+++ b/packages/sdk/src/admin-params.ts
@@ -175,6 +175,35 @@ export interface AdminTaxonUpdateParams {
sort_order?: string;
}
+export interface AdminShipmentUpdateParams {
+ tracking?: string;
+ selected_shipping_rate_id?: string;
+ stock_location_id?: string;
+}
+
+export interface AdminPaymentCreateParams {
+ payment_method_id: string;
+ amount?: number;
+ source_id?: string;
+}
+
+export interface AdminRefundCreateParams {
+ payment_id: string;
+ amount: number;
+ refund_reason_id?: string;
+}
+
+export interface AdminAdjustmentCreateParams {
+ amount: number;
+ label: string;
+}
+
+export interface AdminAdjustmentUpdateParams {
+ amount?: number;
+ label?: string;
+ eligible?: boolean;
+}
+
export interface AdminVariantCreateParams {
sku?: string;
price?: number;
diff --git a/packages/sdk/src/types/generated/AdminAdjustment.ts b/packages/sdk/src/types/generated/AdminAdjustment.ts
new file mode 100644
index 0000000000..76177fc2af
--- /dev/null
+++ b/packages/sdk/src/types/generated/AdminAdjustment.ts
@@ -0,0 +1,21 @@
+// Typelizer digest 7dfe29608c973b1ce4c818108759802c
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+type AdminAdjustment = {
+ id: string;
+ amount: string;
+ label: string | null;
+ eligible: boolean;
+ state: string;
+ included: boolean;
+ created_at: string;
+ updated_at: string;
+ source_type: string | null;
+ source_id: string | null;
+ adjustable_type: string | null;
+ adjustable_id: string | null;
+ order_id: string | null;
+}
+
+export default AdminAdjustment;
diff --git a/packages/sdk/src/types/generated/AdminPayment.ts b/packages/sdk/src/types/generated/AdminPayment.ts
new file mode 100644
index 0000000000..05374f1e32
--- /dev/null
+++ b/packages/sdk/src/types/generated/AdminPayment.ts
@@ -0,0 +1,25 @@
+// Typelizer digest 1967c198f6a46abf66794cbaece1d3fc
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {StoreCreditCard, StoreStoreCredit, StorePaymentSource, StorePaymentMethod} from '@/types'
+
+type AdminPayment = {
+ id: string;
+ payment_method_id: string;
+ state: string;
+ response_code: string | null;
+ number: string;
+ amount: string;
+ display_amount: string;
+ created_at: string;
+ updated_at: string;
+ source_type: 'credit_card' | 'store_credit' | 'payment_source' | null;
+ source_id: string | null;
+ source: StoreCreditCard | StoreStoreCredit | StorePaymentSource | null;
+ payment_method: StorePaymentMethod;
+ metadata: Record<string, unknown> | null;
+ captured_amount: string;
+ order_id: string | null;
+}
+
+export default AdminPayment;
diff --git a/packages/sdk/src/types/generated/AdminRefund.ts b/packages/sdk/src/types/generated/AdminRefund.ts
new file mode 100644
index 0000000000..ca95587f6a
--- /dev/null
+++ b/packages/sdk/src/types/generated/AdminRefund.ts
@@ -0,0 +1,17 @@
+// Typelizer digest 93b5e72105e5f4ed021c6ae112a61e61
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+type AdminRefund = {
+ id: string;
+ transaction_id: string | null;
+ created_at: string;
+ updated_at: string;
+ amount: string | null;
+ payment_id: string | null;
+ refund_reason_id: string | null;
+ reimbursement_id: string | null;
+ metadata: Record<string, unknown> | null;
+}
+
+export default AdminRefund;
diff --git a/packages/sdk/src/types/generated/AdminShipment.ts b/packages/sdk/src/types/generated/AdminShipment.ts
new file mode 100644
index 0000000000..2071add880
--- /dev/null
+++ b/packages/sdk/src/types/generated/AdminShipment.ts
@@ -0,0 +1,25 @@
+// Typelizer digest 771966f3b6a6fa56ddc920d467e1a252
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {StoreShippingMethod, StoreStockLocation, StoreShippingRate} from '@/types'
+
+type AdminShipment = {
+ id: string;
+ number: string;
+ state: string;
+ tracking: string | null;
+ tracking_url: string | null;
+ cost: string;
+ display_cost: string;
+ shipped_at: string | null;
+ created_at: string;
+ updated_at: string;
+ shipping_method: StoreShippingMethod;
+ stock_location: StoreStockLocation;
+ shipping_rates: Array<StoreShippingRate>;
+ metadata: Record<string, unknown> | null;
+ order_id: string | null;
+ stock_location_id: string | null;
+}
+
+export default AdminShipment;
diff --git a/packages/sdk/src/zod/generated/AdminAdjustment.ts b/packages/sdk/src/zod/generated/AdminAdjustment.ts
new file mode 100644
index 0000000000..99414841e0
--- /dev/null
+++ b/packages/sdk/src/zod/generated/AdminAdjustment.ts
@@ -0,0 +1,20 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+
+export const AdminAdjustmentSchema = z.object({
+ id: z.string(),
+ amount: z.string(),
+ label: z.string().nullable(),
+ eligible: z.boolean(),
+ state: z.string(),
+ included: z.boolean(),
+ created_at: z.string(),
+ updated_at: z.string(),
+ source_type: z.string().nullable(),
+ source_id: z.string().nullable(),
+ adjustable_type: z.string().nullable(),
+ adjustable_id: z.string().nullable(),
+ order_id: z.string().nullable(),
+});
+
+export type AdminAdjustment = z.infer<typeof AdminAdjustmentSchema>;
diff --git a/packages/sdk/src/zod/generated/AdminPayment.ts b/packages/sdk/src/zod/generated/AdminPayment.ts
new file mode 100644
index 0000000000..d2be294d19
--- /dev/null
+++ b/packages/sdk/src/zod/generated/AdminPayment.ts
@@ -0,0 +1,24 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+import { StorePaymentMethodSchema } from './StorePaymentMethod';
+
+export const AdminPaymentSchema = z.object({
+ id: z.string(),
+ payment_method_id: z.string(),
+ state: z.string(),
+ response_code: z.string().nullable(),
+ number: z.string(),
+ amount: z.string(),
+ display_amount: z.string(),
+ created_at: z.string(),
+ updated_at: z.string(),
+ source_type: z.string().nullable(),
+ source_id: z.string().nullable(),
+ source: z.any(),
+ payment_method: StorePaymentMethodSchema,
+ metadata: z.record(z.string(), z.unknown()).nullable(),
+ captured_amount: z.string(),
+ order_id: z.string().nullable(),
+});
+
+export type AdminPayment = z.infer<typeof AdminPaymentSchema>;
diff --git a/packages/sdk/src/zod/generated/AdminRefund.ts b/packages/sdk/src/zod/generated/AdminRefund.ts
new file mode 100644
index 0000000000..70e3ddac68
--- /dev/null
+++ b/packages/sdk/src/zod/generated/AdminRefund.ts
@@ -0,0 +1,16 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+
+export const AdminRefundSchema = z.object({
+ id: z.string(),
+ transaction_id: z.string().nullable(),
+ created_at: z.string(),
+ updated_at: z.string(),
+ amount: z.string().nullable(),
+ payment_id: z.string().nullable(),
+ refund_reason_id: z.string().nullable(),
+ reimbursement_id: z.string().nullable(),
+ metadata: z.record(z.string(), z.unknown()).nullable(),
+});
+
+export type AdminRefund = z.infer<typeof AdminRefundSchema>;
diff --git a/packages/sdk/src/zod/generated/AdminShipment.ts b/packages/sdk/src/zod/generated/AdminShipment.ts
new file mode 100644
index 0000000000..054e6e351a
--- /dev/null
+++ b/packages/sdk/src/zod/generated/AdminShipment.ts
@@ -0,0 +1,26 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+import { StoreShippingMethodSchema } from './StoreShippingMethod';
+import { StoreShippingRateSchema } from './StoreShippingRate';
+import { StoreStockLocationSchema } from './StoreStockLocation';
+
+export const AdminShipmentSchema = z.object({
+ id: z.string(),
+ number: z.string(),
+ state: z.string(),
+ tracking: z.string().nullable(),
+ tracking_url: z.string().nullable(),
+ cost: z.string(),
+ display_cost: z.string(),
+ shipped_at: z.string().nullable(),
+ created_at: z.string(),
+ updated_at: z.string(),
+ shipping_method: StoreShippingMethodSchema,
+ stock_location: StoreStockLocationSchema,
+ shipping_rates: z.array(StoreShippingRateSchema),
+ metadata: z.record(z.string(), z.unknown()).nullable(),
+ order_id: z.string().nullable(),
+ stock_location_id: z.string().nullable(),
+});
+
+export type AdminShipment = z.infer<typeof AdminShipmentSchema>;
diff --git a/packages/sdk/tests/admin/adjustments.test.ts b/packages/sdk/tests/admin/adjustments.test.ts
new file mode 100644
index 0000000000..b5e3dd54e7
--- /dev/null
+++ b/packages/sdk/tests/admin/adjustments.test.ts
@@ -0,0 +1,63 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createAdminTestClient } from '../helpers';
+import { adminFixtures } from '../mocks/admin-handlers';
+import type { SpreeClient } from '../../src';
+
+describe('admin / orders.adjustments', () => {
+ let client: SpreeClient;
+ beforeAll(() => { client = createAdminTestClient(); });
+
+ const orderId = 'or_1';
+
+ describe('list', () => {
+ it('returns paginated adjustments', async () => {
+ const result = await client.admin.orders.adjustments.list(orderId);
+
+ expect(result.data).toHaveLength(1);
+ expect(result.data[0].label).toBe('Admin discount');
+ expect(result.meta.page).toBe(1);
+ });
+ });
+
+ describe('create', () => {
+ it('creates an adjustment', async () => {
+ const result = await client.admin.orders.adjustments.create(orderId, {
+ amount: -5.0,
+ label: 'Admin discount',
+ });
+
+ expect(result.id).toBe(adminFixtures.adjustment.id);
+ expect(result.amount).toBe('-5.0');
+ expect(result.label).toBe('Admin discount');
+ });
+ });
+
+ describe('get', () => {
+ it('returns an adjustment by ID', async () => {
+ const result = await client.admin.orders.adjustments.get(orderId, 'adj_1');
+
+ expect(result.id).toBe(adminFixtures.adjustment.id);
+ expect(result.eligible).toBe(true);
+ });
+ });
+
+ describe('update', () => {
+ it('updates an adjustment', async () => {
+ const result = await client.admin.orders.adjustments.update(orderId, 'adj_1', {
+ amount: 10.0,
+ label: 'Updated discount',
+ });
+
+ expect(result.amount).toBe('10.0');
+ expect(result.label).toBe('Updated discount');
+ });
+ });
+
+ describe('delete', () => {
+ it('deletes an adjustment', async () => {
+ await expect(
+ client.admin.orders.adjustments.delete(orderId, 'adj_1')
+ ).resolves.toBeUndefined();
+ });
+ });
+});
diff --git a/packages/sdk/tests/admin/payments.test.ts b/packages/sdk/tests/admin/payments.test.ts
new file mode 100644
index 0000000000..50e57744eb
--- /dev/null
+++ b/packages/sdk/tests/admin/payments.test.ts
@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createAdminTestClient } from '../helpers';
+import { adminFixtures } from '../mocks/admin-handlers';
+import type { SpreeClient } from '../../src';
+
+describe('admin / orders.payments', () => {
+ let client: SpreeClient;
+ beforeAll(() => { client = createAdminTestClient(); });
+
+ const orderId = 'or_1';
+
+ describe('list', () => {
+ it('returns paginated payments', async () => {
+ const result = await client.admin.orders.payments.list(orderId);
+
+ expect(result.data).toHaveLength(1);
+ expect(result.data[0].number).toBe('P100001');
+ expect(result.meta.page).toBe(1);
+ });
+ });
+
+ describe('create', () => {
+ it('creates a payment', async () => {
+ const result = await client.admin.orders.payments.create(orderId, {
+ payment_method_id: 'pm_1',
+ amount: 29.99,
+ });
+
+ expect(result.id).toBe(adminFixtures.payment.id);
+ expect(result.amount).toBe('29.99');
+ });
+ });
+
+ describe('get', () => {
+ it('returns a payment by ID', async () => {
+ const result = await client.admin.orders.payments.get(orderId, 'py_1');
+
+ expect(result.id).toBe(adminFixtures.payment.id);
+ expect(result.state).toBe('completed');
+ });
+ });
+
+ describe('capture', () => {
+ it('captures a payment', async () => {
+ const result = await client.admin.orders.payments.capture(orderId, 'py_1');
+
+ expect(result.state).toBe('completed');
+ });
+ });
+
+ describe('void', () => {
+ it('voids a payment', async () => {
+ const result = await client.admin.orders.payments.void(orderId, 'py_1');
+
+ expect(result.state).toBe('void');
+ });
+ });
+});
diff --git a/packages/sdk/tests/admin/refunds.test.ts b/packages/sdk/tests/admin/refunds.test.ts
new file mode 100644
index 0000000000..ca8b93ead2
--- /dev/null
+++ b/packages/sdk/tests/admin/refunds.test.ts
@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createAdminTestClient } from '../helpers';
+import { adminFixtures } from '../mocks/admin-handlers';
+import type { SpreeClient } from '../../src';
+
+describe('admin / orders.refunds', () => {
+ let client: SpreeClient;
+ beforeAll(() => { client = createAdminTestClient(); });
+
+ const orderId = 'or_1';
+
+ describe('list', () => {
+ it('returns paginated refunds', async () => {
+ const result = await client.admin.orders.refunds.list(orderId);
+
+ expect(result.data).toHaveLength(1);
+ expect(result.data[0].amount).toBe('5.0');
+ expect(result.meta.page).toBe(1);
+ });
+ });
+
+ describe('create', () => {
+ it('creates a refund', async () => {
+ const result = await client.admin.orders.refunds.create(orderId, {
+ payment_id: 'py_1',
+ amount: 5.0,
+ refund_reason_id: 'rr_1',
+ });
+
+ expect(result.id).toBe(adminFixtures.refund.id);
+ expect(result.amount).toBe('5.0');
+ expect(result.payment_id).toBe('py_1');
+ });
+ });
+});
diff --git a/packages/sdk/tests/admin/shipments.test.ts b/packages/sdk/tests/admin/shipments.test.ts
new file mode 100644
index 0000000000..4ce6a99504
--- /dev/null
+++ b/packages/sdk/tests/admin/shipments.test.ts
@@ -0,0 +1,49 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createAdminTestClient } from '../helpers';
+import { adminFixtures } from '../mocks/admin-handlers';
+import type { SpreeClient } from '../../src';
+
+describe('admin / orders.shipments', () => {
+ let client: SpreeClient;
+ beforeAll(() => { client = createAdminTestClient(); });
+
+ const orderId = 'or_1';
+
+ describe('list', () => {
+ it('returns paginated shipments', async () => {
+ const result = await client.admin.orders.shipments.list(orderId);
+
+ expect(result.data).toHaveLength(1);
+ expect(result.data[0].number).toBe('H12345');
+ expect(result.meta.page).toBe(1);
+ });
+ });
+
+ describe('get', () => {
+ it('returns a shipment by ID', async () => {
+ const result = await client.admin.orders.shipments.get(orderId, 'ship_1');
+
+ expect(result.id).toBe(adminFixtures.shipment.id);
+ expect(result.state).toBe('ready');
+ });
+ });
+
+ describe('update', () => {
+ it('updates tracking on a shipment', async () => {
+ const result = await client.admin.orders.shipments.update(orderId, 'ship_1', {
+ tracking: '1Z999AA10123456784',
+ });
+
+ expect(result.tracking).toBe('1Z999AA10123456784');
+ });
+ });
+
+ describe('ship', () => {
+ it('ships a shipment', async () => {
+ const result = await client.admin.orders.shipments.ship(orderId, 'ship_1');
+
+ expect(result.state).toBe('shipped');
+ expect(result.shipped_at).toBeTruthy();
+ });
+ });
+});
diff --git a/packages/sdk/tests/mocks/admin-handlers.ts b/packages/sdk/tests/mocks/admin-handlers.ts
index f801b54ddb..8a5fb7fb9e 100644
--- a/packages/sdk/tests/mocks/admin-handlers.ts
+++ b/packages/sdk/tests/mocks/admin-handlers.ts
@@ -63,6 +63,61 @@ export const adminFixtures = {
permalink: 'categories/clothing',
position: 1,
},
+ shipment: {
+ id: 'ship_1',
+ number: 'H12345',
+ state: 'ready',
+ tracking: null,
+ tracking_url: null,
+ cost: '5.00',
+ display_cost: '$5.00',
+ shipped_at: null,
+ created_at: '2026-03-06T12:00:00.000Z',
+ updated_at: '2026-03-06T12:00:00.000Z',
+ order_id: 'or_1',
+ stock_location_id: 'sl_1',
+ metadata: null,
+ },
+ payment: {
+ id: 'py_1',
+ payment_method_id: 'pm_1',
+ state: 'completed',
+ response_code: '12345',
+ number: 'P100001',
+ amount: '29.99',
+ display_amount: '$29.99',
+ captured_amount: '29.99',
+ created_at: '2026-03-06T12:00:00.000Z',
+ updated_at: '2026-03-06T12:00:00.000Z',
+ order_id: 'or_1',
+ metadata: null,
+ },
+ refund: {
+ id: 're_1',
+ transaction_id: 'txn_123',
+ created_at: '2026-03-06T12:00:00.000Z',
+ updated_at: '2026-03-06T12:00:00.000Z',
+ amount: '5.0',
+ payment_id: 'py_1',
+ refund_reason_id: 'rr_1',
+ reimbursement_id: null,
+ metadata: null,
+ },
+ adjustment: {
+ id: 'adj_1',
+ amount: '-5.0',
+ label: 'Admin discount',
+ eligible: true,
+ state: 'open',
+ source_type: null,
+ source_id: null,
+ adjustable_type: 'Spree::Order',
+ adjustable_id: 'or_1',
+ order_id: 'or_1',
+ included: false,
+ created_at: '2026-03-06T12:00:00.000Z',
+ updated_at: '2026-03-06T12:00:00.000Z',
+ },
};
const paginationMeta = { page: 1, limit: 25, count: 1, pages: 1 };
@@ -274,4 +329,80 @@ export const adminHandlers = [
http.get(`${API_PREFIX}/taxons/:id`, () =>
HttpResponse.json(adminFixtures.taxon)
),
+
+ // ============================================
+ // Order Shipments
+ // ============================================
+ http.get(`${API_PREFIX}/orders/:orderId/shipments`, () =>
+ HttpResponse.json({ data: [adminFixtures.shipment], meta: paginationMeta })
+ ),
+
+ http.get(`${API_PREFIX}/orders/:orderId/shipments/:id`, () =>
+ HttpResponse.json(adminFixtures.shipment)
+ ),
+
+ http.patch(`${API_PREFIX}/orders/:orderId/shipments/:id/ship`, () =>
+ HttpResponse.json({ ...adminFixtures.shipment, state: 'shipped', shipped_at: '2026-03-06T14:00:00.000Z' })
+ ),
+
+ http.patch(`${API_PREFIX}/orders/:orderId/shipments/:id`, () =>
+ HttpResponse.json({ ...adminFixtures.shipment, tracking: '1Z999AA10123456784' })
+ ),
+
+ // ============================================
+ // Order Payments
+ // ============================================
+ http.get(`${API_PREFIX}/orders/:orderId/payments`, () =>
+ HttpResponse.json({ data: [adminFixtures.payment], meta: paginationMeta })
+ ),
+
+ http.post(`${API_PREFIX}/orders/:orderId/payments`, () =>
+ HttpResponse.json(adminFixtures.payment, { status: 201 })
+ ),
+
+ http.get(`${API_PREFIX}/orders/:orderId/payments/:id`, () =>
+ HttpResponse.json(adminFixtures.payment)
+ ),
+
+ http.patch(`${API_PREFIX}/orders/:orderId/payments/:id/capture`, () =>
+ HttpResponse.json({ ...adminFixtures.payment, state: 'completed' })
+ ),
+
+ http.patch(`${API_PREFIX}/orders/:orderId/payments/:id/void`, () =>
+ HttpResponse.json({ ...adminFixtures.payment, state: 'void' })
+ ),
+
+ // ============================================
+ // Order Refunds
+ // ============================================
+ http.get(`${API_PREFIX}/orders/:orderId/refunds`, () =>
+ HttpResponse.json({ data: [adminFixtures.refund], meta: paginationMeta })
+ ),
+
+ http.post(`${API_PREFIX}/orders/:orderId/refunds`, () =>
+ HttpResponse.json(adminFixtures.refund, { status: 201 })
+ ),
+
+ // ============================================
+ // Order Adjustments
+ // ============================================
+ http.get(`${API_PREFIX}/orders/:orderId/adjustments`, () =>
+ HttpResponse.json({ data: [adminFixtures.adjustment], meta: paginationMeta })
+ ),
+
+ http.post(`${API_PREFIX}/orders/:orderId/adjustments`, () =>
+ HttpResponse.json(adminFixtures.adjustment, { status: 201 })
+ ),
+
+ http.get(`${API_PREFIX}/orders/:orderId/adjustments/:id`, () =>
+ HttpResponse.json(adminFixtures.adjustment)
+ ),
+
+ http.patch(`${API_PREFIX}/orders/:orderId/adjustments/:id`, () =>
+ HttpResponse.json({ ...adminFixtures.adjustment, amount: '10.0', label: 'Updated discount' })
+ ),
+
+ http.delete(`${API_PREFIX}/orders/:orderId/adjustments/:id`, () =>
+ new HttpResponse(null, { status: 204 })
+ ),
];
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/adjustments_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/adjustments_controller.rb
new file mode 100644
index 0000000000..f9dd7d5ba5
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/adjustments_controller.rb
@@ -0,0 +1,89 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ module Orders
+ class AdjustmentsController < ResourceController
+ include Spree::Api::V3::OrderLock
+
+ before_action :authorize_order_access!
+ skip_before_action :set_resource, only: [:index, :create]
+ before_action :set_adjustment, only: [:show, :update, :destroy]
+
+ # POST /api/v3/admin/orders/:order_id/adjustments
+ def create
+ with_order_lock do
+ @resource = @parent.adjustments.build(
+ amount: params[:amount],
+ label: params[:label],
+ order: @parent
+ )
+ authorize_resource!(@resource, :create)
+
+ if @resource.save
+ @parent.update_with_updater!
+ render json: serialize_resource(@resource), status: :created
+ else
+ render_validation_error(@resource.errors)
+ end
+ end
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/adjustments/:id
+ def update
+ with_order_lock do
+ if @resource.update(permitted_params)
+ @parent.update_with_updater!
+ render json: serialize_resource(@resource)
+ else
+ render_validation_error(@resource.errors)
+ end
+ end
+ end
+
+ # DELETE /api/v3/admin/orders/:order_id/adjustments/:id
+ def destroy
+ with_order_lock do
+ @resource.destroy!
+ @parent.update_with_updater!
+ head :no_content
+ end
+ end
+
+ protected
+
+ def model_class
+ Spree::Adjustment
+ end
+
+ def serializer_class
+ Spree.api.admin_adjustment_serializer
+ end
+
+ def parent_association
+ :adjustments
+ end
+
+ def set_parent
+ @parent = current_store.orders.find_by_prefix_id!(params[:order_id])
+ @order = @parent
+ end
+
+ def authorize_order_access!
+ authorize!(:show, @parent)
+ end
+
+ def set_adjustment
+ @resource = @parent.adjustments.find_by_prefix_id!(params[:id])
+ authorize_resource!(@resource)
+ end
+
+ def permitted_params
+ params.permit(:amount, :label, :eligible)
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/payments_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/payments_controller.rb
new file mode 100644
index 0000000000..e108425115
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/payments_controller.rb
@@ -0,0 +1,106 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ module Orders
+ class PaymentsController < ResourceController
+ include Spree::Api::V3::OrderLock
+
+ before_action :authorize_order_access!
+ skip_before_action :set_resource, only: [:index, :create]
+ before_action :set_payment, only: [:show, :capture, :void]
+
+ # POST /api/v3/admin/orders/:order_id/payments
+ def create
+ with_order_lock do
+ payment_method = Spree::PaymentMethod.find(params[:payment_method_id])
+ @resource = @parent.payments.build(
+ amount: params[:amount] || @parent.order_total_after_store_credit,
+ payment_method: payment_method
+ )
+
+ if params[:source_id].present? && payment_method.source_required?
+ @resource.source = payment_method.payment_source_class.find_by_prefix_id!(params[:source_id])
+ end
+
+ authorize_resource!(@resource, :create)
+
+ if @resource.save
+ render json: serialize_resource(@resource), status: :created
+ else
+ render_validation_error(@resource.errors)
+ end
+ end
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/payments/:id/capture
+ def capture
+ with_order_lock do
+ amount = params[:amount] ? (params[:amount].to_f * 100).round : nil
+ @resource.capture!(amount)
+ render json: serialize_resource(@resource.reload)
+ rescue Spree::Core::GatewayError => e
+ render_service_error(e.message)
+ end
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/payments/:id/void
+ def void
+ with_order_lock do
+ @resource.void_transaction!
+ render json: serialize_resource(@resource.reload)
+ rescue Spree::Core::GatewayError => e
+ render_service_error(e.message)
+ end
+ end
+
+ protected
+
+ def model_class
+ Spree::Payment
+ end
+
+ def serializer_class
+ Spree.api.admin_payment_serializer
+ end
+
+ def parent_association
+ :payments
+ end
+
+ def set_parent
+ @parent = current_store.orders.find_by_prefix_id!(params[:order_id])
+ @order = @parent
+ end
+
+ def authorize_order_access!
+ authorize!(:show, @parent)
+ end
+
+ def set_payment
+ @resource = @parent.payments.find_by_prefix_id!(params[:id])
+ authorize_resource!(@resource)
+ end
+
+ def permitted_params
+ params.permit(:amount, :payment_method_id, :source_id)
+ end
+
+ private
+
+ def render_result_error(result)
+ error = result.error
+ errors = error.respond_to?(:value) ? error.value : error
+
+ if errors.is_a?(ActiveModel::Errors)
+ render_validation_error(errors)
+ else
+ render_service_error(error)
+ end
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/refunds_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/refunds_controller.rb
new file mode 100644
index 0000000000..af5f38d2f5
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/refunds_controller.rb
@@ -0,0 +1,65 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ module Orders
+ class RefundsController < ResourceController
+ include Spree::Api::V3::OrderLock
+
+ before_action :authorize_order_access!
+ skip_before_action :set_resource, only: [:index, :create]
+
+ # POST /api/v3/admin/orders/:order_id/refunds
+ def create
+ with_order_lock do
+ payment = @parent.payments.find_by_prefix_id!(params[:payment_id])
+ reason = Spree::RefundReason.find_by_prefix_id!(params[:refund_reason_id]) if params[:refund_reason_id].present?
+ reason ||= Spree::RefundReason.first
+
+ @resource = payment.refunds.build(
+ amount: params[:amount],
+ reason: reason,
+ transaction_id: nil
+ )
+ authorize_resource!(@resource, :create)
+
+ if @resource.save
+ render json: serialize_resource(@resource), status: :created
+ else
+ render_validation_error(@resource.errors)
+ end
+ end
+ end
+
+ protected
+
+ def model_class
+ Spree::Refund
+ end
+
+ def serializer_class
+ Spree.api.admin_refund_serializer
+ end
+
+ def set_parent
+ @parent = current_store.orders.find_by_prefix_id!(params[:order_id])
+ @order = @parent
+ end
+
+ def authorize_order_access!
+ authorize!(:show, @parent)
+ end
+
+ def scope
+ Spree::Refund.where(payment_id: @parent.payment_ids)
+ end
+
+ def collection_includes
+ [:payment, :reason]
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/shipments_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/shipments_controller.rb
new file mode 100644
index 0000000000..150b0fcfbb
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/shipments_controller.rb
@@ -0,0 +1,94 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ module Orders
+ class ShipmentsController < ResourceController
+ include Spree::Api::V3::OrderLock
+
+ before_action :authorize_order_access!
+ skip_before_action :set_resource, only: [:index]
+ before_action :set_shipment, only: [:show, :update, :ship]
+
+ # PATCH /api/v3/admin/orders/:order_id/shipments/:id
+ def update
+ with_order_lock do
+ result = Spree.shipment_update_service.call(
+ shipment: @resource,
+ shipment_attributes: permitted_params.to_h
+ )
+
+ if result.success?
+ render json: serialize_resource(@resource.reload)
+ else
+ render_result_error(result)
+ end
+ end
+ end
+
+ # PATCH /api/v3/admin/orders/:order_id/shipments/:id/ship
+ def ship
+ with_order_lock do
+ result = Spree.shipment_change_state_service.call(
+ shipment: @resource,
+ state: 'ship'
+ )
+
+ if result.success?
+ render json: serialize_resource(@resource.reload)
+ else
+ render_service_error(result.error)
+ end
+ end
+ end
+
+ protected
+
+ def model_class
+ Spree::Shipment
+ end
+
+ def serializer_class
+ Spree.api.admin_shipment_serializer
+ end
+
+ def parent_association
+ :shipments
+ end
+
+ def set_parent
+ @parent = current_store.orders.find_by_prefix_id!(params[:order_id])
+ @order = @parent
+ end
+
+ def authorize_order_access!
+ authorize!(:show, @parent)
+ end
+
+ def set_shipment
+ @resource = @parent.shipments.find_by_prefix_id!(params[:id])
+ authorize_resource!(@resource)
+ end
+
+ def permitted_params
+ params.permit(:tracking, :selected_shipping_rate_id, :stock_location_id)
+ end
+
+ private
+
+ def render_result_error(result)
+ error = result.error
+ errors = error.respond_to?(:value) ? error.value : error
+
+ if errors.is_a?(ActiveModel::Errors)
+ render_validation_error(errors)
+ else
+ render_service_error(error)
+ end
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 12f8b67f8a..06cff873b9 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -124,6 +124,19 @@ Spree::Core::Engine.add_routes do
end
resources :line_items, controller: 'orders/line_items'
+ resources :shipments, controller: 'orders/shipments', only: [:index, :show, :update] do
+ member do
+ patch :ship
+ end
+ end
+ resources :payments, controller: 'orders/payments', only: [:index, :show, :create] do
+ member do
+ patch :capture
+ patch :void
+ end
+ end
+ resources :refunds, controller: 'orders/refunds', only: [:index, :create]
+ resources :adjustments, controller: 'orders/adjustments', only: [:index, :show, :create, :update, :destroy]
end
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/adjustments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/adjustments_controller_spec.rb
new file mode 100644
index 0000000000..330c267221
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/adjustments_controller_spec.rb
@@ -0,0 +1,71 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::Orders::AdjustmentsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:order) { create(:order, store: store, state: 'cart') }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #index' do
+ let!(:adjustment) { create(:adjustment, adjustable: order, order: order, amount: 5.00, label: 'Admin discount') }
+
+ it 'returns adjustments for the order' do
+ get :index, params: { order_id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data']).to be_an(Array)
+ expect(json_response['data'].length).to eq(1)
+ end
+ end
+
+ describe 'POST #create' do
+ it 'creates a manual adjustment' do
+ expect {
+ post :create, params: {
+ order_id: order.prefixed_id,
+ amount: -5.00,
+ label: 'Admin discount'
+ }, as: :json
+ }.to change(order.adjustments, :count).by(1)
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['amount']).to eq('-5.0')
+ expect(json_response['label']).to eq('Admin discount')
+ end
+ end
+
+ describe 'PATCH #update' do
+ let!(:adjustment) { create(:adjustment, adjustable: order, order: order, amount: 5.00, label: 'Original') }
+
+ it 'updates the adjustment' do
+ patch :update, params: {
+ order_id: order.prefixed_id,
+ id: adjustment.prefixed_id,
+ amount: 10.00,
+ label: 'Updated'
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['amount']).to eq('10.0')
+ expect(json_response['label']).to eq('Updated')
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ let!(:adjustment) { create(:adjustment, adjustable: order, order: order, amount: 5.00, label: 'To delete') }
+
+ it 'deletes the adjustment' do
+ expect {
+ delete :destroy, params: {
+ order_id: order.prefixed_id,
+ id: adjustment.prefixed_id
+ }, as: :json
+ }.to change(order.adjustments, :count).by(-1)
+
+ expect(response).to have_http_status(:no_content)
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/payments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/payments_controller_spec.rb
new file mode 100644
index 0000000000..5d428c0fcc
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/payments_controller_spec.rb
@@ -0,0 +1,74 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::Orders::PaymentsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:order_with_payment) { create(:order_ready_to_ship, store: store) }
+ let!(:payment) { order_with_payment.payments.first }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #index' do
+ it 'returns payments for the order' do
+ get :index, params: { order_id: order_with_payment.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data']).to be_an(Array)
+ expect(json_response['data'].length).to be >= 1
+ end
+ end
+
+ describe 'GET #show' do
+ it 'returns the payment' do
+ get :show, params: { order_id: order_with_payment.prefixed_id, id: payment.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to eq(payment.prefixed_id)
+ expect(json_response['state']).to be_present
+ end
+ end
+
+ describe 'POST #create' do
+ let(:order) { create(:completed_order_with_totals, store: store) }
+ let(:payment_method) { create(:check_payment_method, stores: [store]) }
+
+ it 'creates a payment' do
+ post :create, params: {
+ order_id: order.prefixed_id,
+ payment_method_id: payment_method.id,
+ amount: order.total
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['state']).to be_present
+ end
+ end
+
+ describe 'PATCH #capture' do
+ before do
+ payment.update_column(:state, 'pending') if payment.state != 'pending'
+ end
+
+ it 'captures the payment' do
+ patch :capture, params: {
+ order_id: order_with_payment.prefixed_id,
+ id: payment.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ end
+ end
+
+ describe 'PATCH #void' do
+ it 'voids the payment' do
+ patch :void, params: {
+ order_id: order_with_payment.prefixed_id,
+ id: payment.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/refunds_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/refunds_controller_spec.rb
new file mode 100644
index 0000000000..6df8e36847
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/refunds_controller_spec.rb
@@ -0,0 +1,43 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::Orders::RefundsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:order) { create(:order_ready_to_ship, store: store) }
+ let!(:payment) { order.payments.first }
+ let!(:refund_reason) { create(:refund_reason) }
+
+ before do
+ request.headers.merge!(headers)
+ end
+
+ describe 'GET #index' do
+ let!(:refund) { create(:refund, payment: payment, amount: 10.0) }
+
+ it 'returns refunds for the order' do
+ get :index, params: { order_id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data']).to be_an(Array)
+ expect(json_response['data'].length).to eq(1)
+ end
+ end
+
+ describe 'POST #create' do
+ it 'creates a refund' do
+ expect {
+ post :create, params: {
+ order_id: order.prefixed_id,
+ payment_id: payment.prefixed_id,
+ refund_reason_id: refund_reason.prefixed_id,
+ amount: 5.00
+ }, as: :json
+ }.to change(Spree::Refund, :count).by(1)
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['amount']).to eq('5.0')
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/shipments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/shipments_controller_spec.rb
new file mode 100644
index 0000000000..79be3ff2d4
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/shipments_controller_spec.rb
@@ -0,0 +1,61 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::Orders::ShipmentsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:order) { create(:order_ready_to_ship, store: store) }
+ let!(:shipment) { order.shipments.first }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #index' do
+ it 'returns shipments for the order' do
+ get :index, params: { order_id: order.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data']).to be_an(Array)
+ expect(json_response['data'].length).to eq(1)
+ end
+ end
+
+ describe 'GET #show' do
+ it 'returns the shipment' do
+ get :show, params: { order_id: order.prefixed_id, id: shipment.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['id']).to eq(shipment.prefixed_id)
+ expect(json_response['number']).to eq(shipment.number)
+ expect(json_response['state']).to eq(shipment.state)
+ end
+ end
+
+ describe 'PATCH #update' do
+ it 'updates shipment tracking' do
+ patch :update, params: {
+ order_id: order.prefixed_id,
+ id: shipment.prefixed_id,
+ tracking: '1Z999AA10123456784'
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(shipment.reload.tracking).to eq('1Z999AA10123456784')
+ end
+ end
+
+ describe 'PATCH #ship' do
+ it 'marks the shipment as shipped' do
+ # Ensure shipment is ready
+ shipment.ready! if shipment.can_ready?
+
+ patch :ship, params: {
+ order_id: order.prefixed_id,
+ id: shipment.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['state']).to eq('shipped')
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/adjustments_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/adjustments_spec.rb
new file mode 100644
index 0000000000..e464176c65
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/adjustments_spec.rb
@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Order Adjustments API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:order) { create(:order, store: store, state: 'cart') }
+ let!(:adjustment) { create(:adjustment, adjustable: order, order: order, amount: 5.00, label: 'Admin discount') }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/orders/{order_id}/adjustments' do
+ let(:order_id) { order.prefixed_id }
+
+ get 'List adjustments' do
+ tags 'Adjustments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns all adjustments for an order.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+
+ response '200', 'adjustments found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ expect(data['data'].length).to be >= 1
+ end
+ end
+ end
+
+ post 'Create an adjustment' do
+ tags 'Adjustments'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Creates a manual adjustment on an order (e.g., admin discount, fee).'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ required: %w[amount label],
+ properties: {
+ amount: { type: :number, example: -5.00, description: 'Negative for discounts, positive for fees' },
+ label: { type: :string, example: 'Admin discount' }
+ }
+ }
+
+ response '201', 'adjustment created' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { amount: -10.00, label: 'VIP discount' } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['amount']).to eq('-10.0')
+ expect(data['label']).to eq('VIP discount')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/adjustments/{id}' do
+ let(:order_id) { order.prefixed_id }
+ let(:id) { adjustment.prefixed_id }
+
+ get 'Show an adjustment' do
+ tags 'Adjustments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns details of a specific adjustment.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Adjustment prefixed ID'
+
+ response '200', 'adjustment found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(adjustment.prefixed_id)
+ end
+ end
+ end
+
+ patch 'Update an adjustment' do
+ tags 'Adjustments'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Updates an adjustment amount or label.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Adjustment prefixed ID'
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ amount: { type: :number },
+ label: { type: :string },
+ eligible: { type: :boolean }
+ }
+ }
+
+ response '200', 'adjustment updated' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { amount: 15.00, label: 'Updated discount' } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['amount']).to eq('15.0')
+ expect(data['label']).to eq('Updated discount')
+ end
+ end
+ end
+
+ delete 'Delete an adjustment' do
+ tags 'Adjustments'
+ security [api_key: [], bearer_auth: []]
+ description 'Deletes an adjustment from an order.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Adjustment prefixed ID'
+
+ response '204', 'adjustment deleted' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/payments_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/payments_spec.rb
new file mode 100644
index 0000000000..715f1f30dc
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/payments_spec.rb
@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Order Payments API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:order) { create(:order_ready_to_ship, store: store) }
+ let!(:payment) { order.payments.first }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/orders/{order_id}/payments' do
+ let(:order_id) { order.prefixed_id }
+
+ get 'List payments' do
+ tags 'Payments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns all payments for an order.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+
+ response '200', 'payments found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ expect(data['data'].length).to be >= 1
+ end
+ end
+ end
+
+ post 'Create a payment' do
+ tags 'Payments'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Creates a new payment for the order.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ required: %w[payment_method_id],
+ properties: {
+ payment_method_id: { type: :string, description: 'Payment method ID or prefixed ID' },
+ amount: { type: :number, example: 99.99 },
+ source_id: { type: :string, description: 'Payment source prefixed ID' }
+ }
+ }
+
+ response '201', 'payment created' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:order_without_payment) { create(:completed_order_with_totals, store: store) }
+ let(:order_id) { order_without_payment.prefixed_id }
+ let(:payment_method) { create(:check_payment_method, stores: [store]) }
+ let(:body) { { payment_method_id: payment_method.id, amount: order_without_payment.total } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['state']).to be_present
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/payments/{id}' do
+ let(:order_id) { order.prefixed_id }
+ let(:id) { payment.prefixed_id }
+
+ get 'Show a payment' do
+ tags 'Payments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns details of a specific payment.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Payment prefixed ID'
+
+ response '200', 'payment found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(payment.prefixed_id)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/payments/{id}/capture' do
+ patch 'Capture a payment' do
+ tags 'Payments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Captures a pending payment.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Payment prefixed ID'
+
+ response '200', 'payment captured' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:order_id) { order.prefixed_id }
+ let(:id) { payment.prefixed_id }
+
+ before do
+ payment.update_column(:state, 'pending') if payment.state != 'pending'
+ end
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(payment.prefixed_id)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/payments/{id}/void' do
+ patch 'Void a payment' do
+ tags 'Payments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Voids a payment.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Payment prefixed ID'
+
+ response '200', 'payment voided' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:order_id) { order.prefixed_id }
+ let(:id) { payment.prefixed_id }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(payment.prefixed_id)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/refunds_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/refunds_spec.rb
new file mode 100644
index 0000000000..7e740e1bc4
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/refunds_spec.rb
@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Order Refunds API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:order) { create(:order_ready_to_ship, store: store) }
+ let!(:payment) { order.payments.first }
+ let!(:refund_reason) { create(:refund_reason) }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/orders/{order_id}/refunds' do
+ let(:order_id) { order.prefixed_id }
+
+ get 'List refunds' do
+ tags 'Refunds'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns all refunds for an order.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+
+ response '200', 'refunds found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ end
+ end
+ end
+
+ post 'Create a refund' do
+ tags 'Refunds'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ required: %w[payment_id amount],
+ properties: {
+ payment_id: { type: :string, description: 'Payment prefixed ID' },
+ amount: { type: :number, example: 10.00 },
+ refund_reason_id: { type: :string, description: 'Refund reason prefixed ID' }
+ }
+ }
+
+ response '201', 'refund created' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { payment_id: payment.prefixed_id, amount: 5.00, refund_reason_id: refund_reason.prefixed_id } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['amount']).to eq('5.0')
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/shipments_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/shipments_spec.rb
new file mode 100644
index 0000000000..ecc2c5172c
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/shipments_spec.rb
@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Order Shipments API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:order) { create(:order_ready_to_ship, store: store) }
+ let!(:shipment) { order.shipments.first }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/orders/{order_id}/shipments' do
+ let(:order_id) { order.prefixed_id }
+
+ get 'List shipments' do
+ tags 'Shipments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns all shipments for an order.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+
+ response '200', 'shipments found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ expect(data['data'].length).to eq(1)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/shipments/{id}' do
+ let(:order_id) { order.prefixed_id }
+ let(:id) { shipment.prefixed_id }
+
+ get 'Show a shipment' do
+ tags 'Shipments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns details of a specific shipment.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Shipment prefixed ID'
+
+ response '200', 'shipment found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(shipment.prefixed_id)
+ expect(data['number']).to be_present
+ end
+ end
+ end
+
+ patch 'Update a shipment' do
+ tags 'Shipments'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Updates a shipment (tracking, shipping rate).'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Shipment prefixed ID'
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ tracking: { type: :string, example: '1Z999AA10123456784' },
+ selected_shipping_rate_id: { type: :string }
+ }
+ }
+
+ response '200', 'shipment updated' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { tracking: '1Z999AA10123456784' } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['tracking']).to eq('1Z999AA10123456784')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/shipments/{id}/ship' do
+ patch 'Ship a shipment' do
+ tags 'Shipments'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Marks a shipment as shipped.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :order_id, in: :path, type: :string, required: true,
+ description: 'Order prefixed ID'
+ parameter name: :id, in: :path, type: :string, required: true,
+ description: 'Shipment prefixed ID'
+
+ response '200', 'shipment shipped' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:order_id) { order.prefixed_id }
+ let(:id) { shipment.prefixed_id }
+
+ before do
+ shipment.ready! if shipment.can_ready?
+ end
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['state']).to eq('shipped')
+ end
+ end
+ end
+ end
+end