0
# Medusa Fulfillment Manual
1

2
Medusa Fulfillment Manual is a minimal fulfillment provider plugin for the Medusa e-commerce platform. It provides a "no-operation" fulfillment service that allows merchants to handle order fulfillments manually through the Medusa admin interface, without integrating with external shipping services.
3

4
## Package Information
5

6
- **Package Name**: medusa-fulfillment-manual
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES6)
9
- **Installation**: `npm install medusa-fulfillment-manual`
10
- **Plugin Type**: Medusa fulfillment provider
11

12
## Core Imports
13

14
As a Medusa plugin, this package is typically not imported directly in application code. Instead, it's registered through the Medusa configuration and accessed via dependency injection:
15

16
```javascript
17
// The service is available through Medusa's container system
18
const manualFulfillmentService = container.resolve("manualFulfillmentService");
19
```
20

21
For direct access to the service class (development/testing):
22

23
```javascript
24
import ManualFulfillmentService from "medusa-fulfillment-manual/src/services/manual-fulfillment";
25
```
26

27
## Basic Usage
28

29
This package is designed to be used as a Medusa plugin. Add it to your `medusa-config.js`:
30

31
```javascript
32
const plugins = [
33
  // ... other plugins
34
  "medusa-fulfillment-manual"
35
];
36

37
module.exports = {
38
  projectConfig: {
39
    // ... other config
40
  },
41
  plugins,
42
};
43
```
44

45
Once configured, the manual fulfillment provider becomes available in the Medusa admin for creating shipping options and handling fulfillments manually.
46

47
## Architecture
48

49
The package implements the Medusa fulfillment provider interface through a single service class:
50

51
- **ManualFulfillmentService**: Main service extending Medusa's `FulfillmentService` base class
52
- **No-operation Pattern**: All fulfillment operations return empty promises/objects
53
- **Manual Processing**: Designed for merchants who prefer manual shipping processes
54
- **Reference Implementation**: Serves as a template for custom fulfillment providers
55

56
## Capabilities
57

58
### Manual Fulfillment Service
59

60
The core service class that provides manual fulfillment capabilities for Medusa stores.
61

62
```javascript { .api }
63
/**
64
 * Manual fulfillment service that extends Medusa's FulfillmentService
65
 * Provides no-operation implementations for all fulfillment operations
66
 */
67
class ManualFulfillmentService extends FulfillmentService {
68
  /** Unique identifier for this fulfillment provider */
69
  static identifier: string; // "manual"
70

71
  constructor();
72

73
  /** Returns available fulfillment options for orders and returns */
74
  getFulfillmentOptions(): FulfillmentOption[];
75

76
  /** Validates fulfillment data (pass-through implementation) */
77
  validateFulfillmentData(
78
    optionData: any,
79
    data: any,
80
    cart: any
81
  ): any;
82

83
  /** Validates fulfillment options (always returns true) */
84
  validateOption(data: any): boolean;
85

86
  /** Indicates whether service can calculate shipping prices */
87
  canCalculate(): boolean; // Always returns false
88

89
  /** Throws error - manual service cannot calculate prices */
90
  calculatePrice(): never;
91

92
  /** Creates order fulfillment (no-operation) */
93
  createOrder(): Promise<{}>;
94

95
  /** Creates return fulfillment (no-operation) */
96
  createReturn(): Promise<{}>;
97

98
  /** Creates fulfillment (no-operation) */
99
  createFulfillment(): Promise<{}>;
100

101
  /** Cancels fulfillment (no-operation) */
102
  cancelFulfillment(): Promise<{}>;
103

104
  /** Retrieves fulfillment documents (returns empty array) */
105
  retrieveDocuments(): Promise<[]>;
106
}
107
```
108

109
### Fulfillment Options
110

111
The service provides two predefined fulfillment options.
112

113
```javascript { .api }
114
/**
115
 * Fulfillment option configuration
116
 */
117
interface FulfillmentOption {
118
  /** Unique identifier for the fulfillment option */
119
  id: string;
120
  /** Optional flag indicating if this is a return option */
121
  is_return?: boolean;
122
}
123
```
124

125
**Available Options:**
126
- `{ id: "manual-fulfillment" }` - Standard fulfillment option
127
- `{ id: "manual-fulfillment-return", is_return: true }` - Return fulfillment option
128

129
### Service Identifier
130

131
Static identifier used by Medusa to register the fulfillment provider.
132

133
```javascript { .api }
134
/**
135
 * Static identifier for the manual fulfillment provider
136
 * Used by Medusa to register and identify this provider
137
 */
138
static identifier = "manual";
139
```
140

141
### Validation Methods
142

143
Methods for validating fulfillment data and options.
144

145
```javascript { .api }
146
/**
147
 * Validates fulfillment data before processing
148
 * @param optionData - Option-specific data (unused)
149
 * @param data - Fulfillment data to validate
150
 * @param cart - Cart object (unused)
151
 * @returns The original data unchanged
152
 */
153
validateFulfillmentData(optionData: any, data: any, cart: any): any;
154

155
/**
156
 * Validates fulfillment options
157
 * @param data - Option data to validate
158
 * @returns true - Always validates successfully
159
 */
160
validateOption(data: any): boolean;
161
```
162

163
### Price Calculation
164

165
Methods related to shipping price calculation (not supported).
166

167
```javascript { .api }
168
/**
169
 * Indicates whether this service can calculate shipping prices
170
 * @returns false - Manual service cannot calculate prices
171
 */
172
canCalculate(): boolean;
173

174
/**
175
 * Attempts to calculate shipping price
176
 * @throws Error - Manual Fulfillment service cannot calculatePrice
177
 */
178
calculatePrice(): never;
179
```
180

181
### Fulfillment Operations
182

183
Core fulfillment operations that return empty promises.
184

185
```javascript { .api }
186
/**
187
 * Creates an order fulfillment
188
 * @returns Promise resolving to empty object
189
 */
190
createOrder(): Promise<{}>;
191

192
/**
193
 * Creates a return fulfillment  
194
 * @returns Promise resolving to empty object
195
 */
196
createReturn(): Promise<{}>;
197

198
/**
199
 * Creates a fulfillment
200
 * @returns Promise resolving to empty object
201
 */
202
createFulfillment(): Promise<{}>;
203

204
/**
205
 * Cancels a fulfillment
206
 * @returns Promise resolving to empty object
207
 */
208
cancelFulfillment(): Promise<{}>;
209

210
/**
211
 * Retrieves fulfillment documents
212
 * @returns Promise resolving to empty array
213
 */
214
retrieveDocuments(): Promise<[]>;
215
```
216

217
## Types
218

219
```javascript { .api }
220
/**
221
 * Base class from medusa-interfaces
222
 */
223
abstract class FulfillmentService {
224
  // Base implementation provided by Medusa
225
}
226
```
227

228
## Error Handling
229

230
The service throws one specific error:
231

232
- **calculatePrice()**: Throws `Error("Manual Fulfillment service cannot calculatePrice")` when attempting to calculate prices
233

234
All other methods are designed to succeed with no-operation implementations.
235

236
## Usage Notes
237

238
- This provider is intended for stores that handle shipping manually
239
- No external shipping service integration is provided
240
- All fulfillment operations return empty results
241
- Price calculation is not supported and will throw an error
242
- Serves as a reference implementation for custom fulfillment providers
243
- Must be registered as a plugin in Medusa configuration