Vendure Drop Off Points Plugin

view v1.3.0 on npmChangelog

npm install @pinelab/vendure-plugin-drop-off-points

Vendure Drop Off Points Plugin

Show nearby parcel drop off points to your customers. Supports multiple carriers and allows custom carriers. Also known as collection points or pickup points.

Getting started

Add the plugin to your vendure-config.ts:

// vendure-config
import {
  DropOffPointsPlugin,
  DHLCarrier,
} from '@pinelab/vendure-plugin-drop-off-points';

plugins: [
  DropOffPointsPlugin.init({
    carriers: [
      new DHLCarrier(),
      // You can add more custom carriers here
    ],
  }),
];

Run a database migration to add the drop off point custom fields to an order. If you want to use your own custom fields, see “Using your own custom fields” below.

Storefront usage

1. Fetch nearby drop off points:

   query {
     parcelDropOffPoints(
       input: { carrier: "DHL", postalCode: "8932BR", houseNumber: "48" }
     ) {
       token
       dropOffPointId
       name
       streetLine1
       streetLine2
       postalCode
       houseNumber
       houseNumberSuffix
       city
       country
       latitude
       longitude
       distanceInKm
       cutOffTime
       additionalData
     }
   }

2. Set the selected drop off point on the order:

   mutation {
    setParcelDropOffPoint(token: ${selectedPoint.token} ) {
        id
        code
        customFields {
        dropOffPointCarrier
        dropOffPointId
        dropOffPointName
        dropOffPointStreetLine1
        dropOffPointStreetLine2
        dropOffPointHouseNumber
        dropOffPointHouseNumberSuffix
        dropOffPointPostalCode
        dropOffPointCity
        dropOffPointCountry
        }
      }
    }

   If your customer decides to not use a drop off point, you should call unsetParcelDropOffPoint to void all the fields again.

Using your own custom fields

By default, this plugin creates the following custom fields on an order: dropOffPointCarrier, dropOffPointId, dropOffPointName, dropOffPointStreetLine1, dropOffPointStreetLine2, dropOffPointHouseNumber, dropOffPointHouseNumberSuffix, dropOffPointPostalCode, dropOffPointCity, dropOffPointCountry.

If you would like to use your own custom fields for drop off points, you can implement the setDropOffPointOnOrder and unsetDropOffPoint functions, like so:

vendure-config.ts

DropOffPointsPlugin.init({
  carriers: [new DHLCarrier()],
  // Use your own custom fields here
  customMutations: {
    setDropOffPointOnOrder: (ctx, order, dropOffPoint) => {
      order.customFields.pickupPointName = dropOffPoint.name;
      // Other fields go here
      return order;
    },
    unsetDropOffPoint: (ctx, order) => {
      order.customFields.pickupPointName = null;
      // Other fields go here
      return order;
    }
  }
}),

If you supply customMutations in the plugin config, you don’t have to do a database migration, because the plugin will not add any custom fields to the order.

Custom carriers

You can easily implement your own drop off point carriers, by implementing the DropOffPointCarrier interface.

my-custom-carrier.ts

import { RequestContext } from '@vendure/core';
import {
  DropOffPoint,
  DropOffPointCarrier,
  ParcelDropOffPointSearchInput,
} from '@pinelab/vendure-plugin-drop-off-points';

export class CustomCarrier implements DropOffPointCarrier {
  readonly name = 'CustomCarrier';

  async getDropOffPoints(
    ctx: RequestContext,
    input: ParcelDropOffPointSearchInput
  ): Promise<DropOffPoint[]> {
    let url = `https://my-carrier-api.com/pickup-points=postalcode=${input.postalCode}`;
    if (input.houseNumber) {
      url += `&houseNumber=${input.houseNumber}`;
    }
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(
        `Failed to fetch drop-off points: [${response.status}] ${response.statusText}`
      );
    }
    const points = (await response.json()) as any;
    return points.map((point) => ({
      dropOffPointId: point.id,
      name: point.name,
      houseNumber: point.address.number,
      houseNumberSuffix: point.address.addition,
      streetLine1: point.address.street,
      streetLine2: undefined,
      postalCode: point.address.postalCode,
      city: point.address.city,
      country: point.address.countryCode,
      cutOffTime: point.collectionSchedule.time,
      latitude: point.geoLocation.latitude,
      longitude: point.geoLocation.longitude,
      distanceInKm: point.distance,
    }));
  }
}

You can then pass it into the plugin:

// vendure-config

plugins: [
  DropOffPointsPlugin.init({
    carriers: [new CustomCarrier()],
  }),
];

Why are ID’s/tokens so long?

TL;DR: Avoid an extra API call to drop off point carrier.

The drop off point’s token is a base64 encoded string of the address details of a point. This is used to save the drop off point on an order when you call the setParcelDropOffPoint mutation, without the need to refetch the points from the external API.