Skip to main content

FulfillmentHandler

FulfillmentHandler​

@vendure/corefulfillment-handler.ts

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>)
}

constructor​

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

FulfillmentHandlerConfig​

@vendure/corefulfillment-handler.ts

The configuration object used to instantiate a FulfillmentHandler.

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

createFulfillment​

property
CreateFulfillmentFn<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​

property
OnTransitionStartFn<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.

CreateFulfillmentFn​

@vendure/corefulfillment-handler.ts

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>

CreateFulfillmentResult​

@vendure/corefulfillment-handler.ts
Signature
type CreateFulfillmentResult = Partial<Pick<Fulfillment, 'trackingCode' | 'method' | 'customFields'>>