FulfillmentHandler

@vendure/core Source

A FulfillmentHandler is used when creating a new Fulfillment. When the addFulfillmentToOrder mutation is executed, the specified handler will be used and it's createFulfillment method is called. This method may perform async tasks such as calling a 3rd-party shipping API to register a new shipment and receive a tracking code. This data can then be returned and will be incorporated into the created Fulfillment.

If the args property is defined, this means that arguments passed to the addFulfillmentToOrder mutation will be passed through to the createFulfillment method as the last argument.

Example

let shipomatic;export const shipomaticFulfillmentHandler = new FulfillmentHandler({  code: 'ship-o-matic',  description: [{    languageCode: LanguageCode.en,    value: 'Generate tracking codes via the Ship-o-matic API'  }],  args: {    preferredService: {      type: 'string',      ui: {        component: 'select-form-input',        options: [          { value: 'first_class' },          { value: 'priority'},          { value: 'standard' },        ],      },    }  },  init: () => {    // some imaginary shipping service    shipomatic = new ShipomaticClient(API_KEY);  },  createFulfillment: async (ctx, orders, lines, args) => {     const shipment = getShipmentFromOrders(orders, lines);     try {       const transaction = await shipomatic.transaction.create({         shipment,         service_level: args.preferredService,         label_file_type: 'png',       })       return {         method: `Ship-o-matic ${args.preferredService}`,         trackingCode: transaction.tracking_code,         customFields: {           shippingTransactionId: transaction.id,         }       };     } catch (e: any) {       // Errors thrown from within this function will       // result in a CreateFulfillmentError being returned       throw e;     }  },  onFulfillmentTransition: async (fromState, toState, { fulfillment }) => {    if (toState === 'Cancelled') {      await shipomatic.transaction.cancel({        transaction_id: fulfillment.customFields.shippingTransactionId,      });    }  }});

Signature

class FulfillmentHandler<T extends ConfigArgs = ConfigArgs> extends ConfigurableOperationDef<T> {    constructor(config: FulfillmentHandlerConfig<T>)}

Extends: ConfigurableOperationDef<T>

constructor

method(config: FulfillmentHandlerConfig<T>) => FulfillmentHandler

@vendure/core Source

The configuration object used to instantiate a FulfillmentHandler.

Signature

interface FulfillmentHandlerConfig<T extends ConfigArgs> extends ConfigurableOperationDefOptions<T> {    createFulfillment: CreateFulfillmentFn<T>;    onFulfillmentTransition?: OnTransitionStartFn<FulfillmentState, FulfillmentTransitionData>;}

Extends: ConfigurableOperationDefOptions<T>

createFulfillment

propertyCreateFulfillmentFn<T>

Invoked when the addFulfillmentToOrder mutation is executed with this handler selected.

If an Error is thrown from within this function, no Fulfillment is created and the CreateFulfillmentError result will be returned.

onFulfillmentTransition

propertyOnTransitionStartFn<FulfillmentState, FulfillmentTransitionData>

This allows the handler to intercept state transitions of the created Fulfillment. This works much in the same way as the FulfillmentProcess onTransitionStart method (i.e. returning false or string will be interpreted as an error and prevent the state transition), except that it is only invoked on Fulfillments which were created with this particular FulfillmentHandler.

It can be useful e.g. to intercept Fulfillment cancellations and relay that information to a 3rd-party shipping API.

@vendure/core Source

The function called when creating a new Fulfillment

Signature

type CreateFulfillmentFn<T extends ConfigArgs> = (    ctx: RequestContext,    orders: Order[],    lines: OrderLineInput[],    args: ConfigArgValues<T>,) => CreateFulfillmentResult | Promise<CreateFulfillmentResult>

@vendure/core Source

Signature

type CreateFulfillmentResult = Partial<Pick<Fulfillment, 'trackingCode' | 'method' | 'customFields'>>