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

Vendure Drop Off Points Plugin

Official documentation here

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

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

• 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.