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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex 12f8b67f8a..06cff873b9 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -124,6 +124,19 @@ Spree::Core::Engine.add_routes doendresources :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]endendenddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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+enddiff --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.rbnew file mode 100644index 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