FulfillmentHandler

FulfillmentHandler

FulfillmentHandler

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, orderItems, args) => {

     const shipment = getShipmentFromOrders(orders, orderItems);

     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) {
       // 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

Members

constructor

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

FulfillmentHandlerConfig

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

Members

createFulfillment

property

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

This allows the handler to intercept state transitions of the created Fulfillment. This works much in the same way as the CustomFulfillmentProcess 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

The function called when creating a new Fulfillment

Signature

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

CreateFulfillmentResult

Signature

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