Delivery options

Looking for…

1 · Install

Option A — CDN (fastest, no build step)

Two variants: either you load Vue yourself, or you use the bundle that includes Vue.

<!-- Variant 1: load Vue yourself -->
<script src="https://cdn.jsdelivr.net/npm/vue@3.4"></script>
<script src="https://cdn.jsdelivr.net/npm/@myparcel/delivery-options@6/dist/myparcel.lib.js"></script>
<link  rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@myparcel/delivery-options@6/dist/style.css" />

<!-- Variant 2: bundle including Vue -->
<script src="https://cdn.jsdelivr.net/npm/@myparcel/delivery-options@6/dist/myparcel.js"></script>
<link  rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@myparcel/delivery-options@6/dist/style.css" />

Option B — npm

npm install @myparcel/delivery-options

import '@myparcel/delivery-options/dist/myparcel.js';
import '@myparcel/delivery-options/dist/style.css';

For Vue 3 projects that import the component directly, use the /lib export (see §3 · Vue 3).

Requirements

2 · Architecture at a glance

┌──────────────┐    update event        ┌──────────────┐
│  your        │ ─────────────────────► │  Delivery    │
│  checkout    │   (CustomEvent)        │  Options     │
└──────────────┘                        │  widget      │
       ▲       ◄───────────────────────  │  (Vue 3)     │
       │       updated/error event       └──────────────┘
       │                                        │
       └────────► POST /shipments  ◄────────────┘
                  (selection payload)

Three integration points:

1. Init — give the widget a configuration (address + carrier settings) via a prop or via dispatchEvent('myparcel_update_delivery_options', { detail: config }).
2. Selection — the widget renders inside <div id="myparcel-delivery-options">, the user picks an option, you catch myparcel_updated_delivery_options.
3. Submit — on checkout submit you take the latest payload and forward it to /shipments (REST API or via the PHP SDK / JS SDK).

3 · Initialise

Vue 3 component

import { ref, type Ref } from 'vue';
import {
  MyParcelDeliveryOptions,
  type InputDeliveryOptionsConfiguration,
} from '@myparcel/delivery-options/lib';

const configuration: Ref<InputDeliveryOptionsConfiguration> = ref({
  address: {
    cc: 'NL',
    postalCode: '2132JE',
    number: '31',
    street: 'Antareslaan 31',
    city: 'Hoofddorp',
  },
  config: {
    platform: 'myparcel',
    carrierSettings: {
      postnl: {},
    },
  },
});

<template>
  <MyParcelDeliveryOptions :configuration="configuration" />
</template>

<style>
@import '@myparcel/delivery-options/style.css';
</style>

Mutating configuration.value re-renders the widget — useful when the address only becomes known later in the checkout flow.

Plain JavaScript / non-Vue

HTML mount point:

<div id="myparcel-delivery-options"></div>

Initialise via a CustomEvent:

const configuration = {
  selector: '#myparcel-delivery-options',
  address: {
    cc: 'NL',
    postalCode: '2132JE',
    number: '31',
    street: 'Antareslaan 31',
    city: 'Hoofddorp',
  },
  config: {
    platform: 'myparcel',
    carrierSettings: {
      postnl: {},
    },
  },
};

document.dispatchEvent(
  new CustomEvent('myparcel_update_delivery_options', { detail: configuration }),
);

4 · Events

Inbound — update config

Outbound — selection and errors

Selection payload

{
  "carrier": "postnl",
  "date": "2026-04-10 00:00:00.000000",
  "deliveryType": "morning",
  "isPickup": false,
  "packageType": "package",
  "shipmentOptions": {
    "signature": true,
    "onlyRecipient": true
  }
}

For isPickup: true the payload also contains a pickupLocation object with locationCode, retailNetworkId, street, number, postalCode, city, cc, latitude, longitude and openingHours.

Listener

document.addEventListener('myparcel_updated_delivery_options', (event) => {
  // persist in state — e.g. Vuex/Pinia/Redux/sessionStorage
  window.__lastDeliveryChoice = event.detail;
});

document.addEventListener('myparcel_error_delivery_options', (event) => {
  // show a friendly error to the customer; log to Sentry/Datadog
  console.error(event.detail.exception);
});

Error codes (selection)

The full set lives in src/types/events.types.ts ↗ and the runtime validation in src/config/validateConfiguration.ts ↗.

5 · Carriers and options

carrierSettings accepts a separate block per carrier. An empty {} means: use the account defaults from the MyParcel backoffice.

config: {
  platform: 'myparcel',
  carrierSettings: {
    postnl: {
      allowMorningDelivery: true,
      allowEveningDelivery: true,
      priceMorningDelivery: 195,   // cents
      priceEveningDelivery: 195,
      allowPickupLocations: true,
    },
    dhlforyou: {
      allowEveningDelivery: true,  // since v6.25
    },
  },
},

Per carrier, only the options that the carrier and your shop contract support are shown. The widget hides unavailable combinations on its own.

6 · Configuration reference

This is how configuration is organised:

type InputDeliveryOptionsConfiguration = {
  address?: AddressInput;
  config: {
    platform: 'myparcel' | 'sendmyparcel';
    locale?: string;            // e.g. 'nl-NL', 'nl-BE', 'fr-BE'
    carrierSettings: Record<string, CarrierSetting>;
    // ...display & feature flags below
  };
  strings?: Partial<Record<StringsKey, string>>;
};

Top-level config

Display settings

Delivery options (set per carrierSettings.<carrier> for finer-grained control)

Shipment options (per shipment, on top of the delivery option)

Pickup

Package types

Full type definition

The authoritative source for all keys: @myparcel-dev/do-shared ↗ — exported as InputDeliveryOptionsConfiguration and DeliveryOptionsConfiguration.

7 · Drop-off days and cutoff

Determines when an order still goes to the carrier the same day. This affects which delivery dates the widget shows.

Simple — one cutoff for all drop-off days

{
  cutoffTime: '16:00',
  sameDayCutoffTime: '09:30',
  dropOffDays: '1,2,3,4,5',     // Mon–Fri; also valid: [1,2,3,4,5] or '1;2;3;4;5'
  dropOffDelay: 0,              // days between order and drop-off
  deliveryDaysWindow: 7,        // how many days ahead are shown
}

A separate cutoff per day

{
  cutoffTime: '15:00',          // fallback
  sameDayCutoffTime: '09:30',
  dropOffDays: [
    1,                                // Monday — uses the fallback cutoff
    { day: 2, cutoffTime: '16:00', sameDayCutoffTime: '10:00' },
    { day: 3 },
    { day: 5, cutoffTime: '14:00' },
  ],
  closedDays: ['2026-12-25', '2026-12-26'],  // shop closure (since v6.19)
}

closedDays (v6.19.0+) blocks specific calendar dates without you having to rework dropOffDays.

8 · Pickup points

By default you get a list view; users can switch to a map when allowPickupLocationsViewSelection: true.

Custom map tiles (Mapbox / MapTiler)

pickupLocationsMapTileLayerData: {
  url: 'https://api.maptiler.com/maps/streets-v2/{z}/{x}/{y}.png?key=YOUR_KEY',
  attribution: '© MapTiler © OpenStreetMap contributors',
  minZoom: 1,
  maxZoom: 18,
}

Without this key the widget falls back to OpenStreetMap tiles.

Selection payload for pickup

{
  "carrier": "postnl",
  "date": "2026-04-12 00:00:00.000000",
  "deliveryType": "pickup",
  "isPickup": true,
  "packageType": "package",
  "pickupLocation": {
    "locationCode": "169177",
    "retailNetworkId": "PNPNL-01",
    "locationName": "Albert Heijn",
    "street": "Hoofdstraat",
    "number": "1",
    "postalCode": "1012AB",
    "city": "Amsterdam",
    "cc": "NL",
    "latitude": 52.3702,
    "longitude": 4.8952,
    "openingHours": { "monday": [{ "from": "08:00", "to": "20:00" }] }
  },
  "shipmentOptions": {}
}

9 · Handling the selection

The event payload maps 1-to-1 onto the options object of POST /shipments:

document.addEventListener('myparcel_updated_delivery_options', async (event) => {
  const choice = event.detail;

  await fetch('/api/checkout/delivery-choice', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      carrier:      choice.carrier,
      delivery_date: choice.date,
      delivery_type: choice.deliveryType,
      package_type:  choice.packageType,
      pickup:        choice.pickupLocation ?? null,
      options:       choice.shipmentOptions,
    }),
  });
});

Persist server-side, not just in localStorage — localStorage doesn't survive a tab change or refresh cycle, and the choice belongs to the order, not the browser.

10 · Migrate v5 → v6

Main breaking changes (full story: §Upgrading on the old page ↗):

Versions since v6.18 (quick changelog)

Full changelog: apps/delivery-options/CHANGELOG.md ↗.

11 · Sandbox and debugging

• Sandbox — myparcelnl.github.io/delivery-options ↗ — interactive playground. Change any key, see the UI and event payload react instantly.
• GitHub releases — github.com/myparcelnl/delivery-options/releases ↗ — versions, breaking changes, jsdelivr URLs.
• DevTools — listen in the console: document.addEventListener('myparcel_updated_delivery_options', e => console.log(e.detail)). Helpful when debugging why a choice doesn't come through.
• Issue tracker — github.com/myparcelnl/delivery-options/issues ↗ — open an issue with behaviour you can reproduce in the sandbox.

12 · Combining with the SDKs

The widget event hands you the selection; the SDKs build consignments from it:

// PHP — via myparcelnl/sdk
use MyParcelNL\Sdk\Factory\DeliveryOptionsAdapterFactory;

$adapter = DeliveryOptionsAdapterFactory::create($_POST['delivery_choice']);
$consignment->setDeliveryDate($adapter->getDate())
            ->setDeliveryType($adapter->getDeliveryTypeId())
            ->setPackageType($adapter->getPackageTypeId());

// TypeScript — via @myparcelnl/sdk (JS SDK)
import { MyParcel } from '@myparcelnl/sdk';

const mp = new MyParcel({ /* ... */ });
const shipment = await mp.shipments.create({
  carrier:      choice.carrier,
  delivery_date: choice.date,
  recipient:    customerAddress,
  options:      { ...choice.shipmentOptions, package_type: choice.packageType },
});

See the PHP SDK and JavaScript SDK for the full consignment flow.