PHP SDK

Looking for…

1 · Install

composer require myparcelnl/sdk

PSR-4 autoload — no manual require needed. Source: Packagist ↗.

Requirements

Composer constraint: "php": "^7.4 || ^8.0". PHP versions below 7.4 are no longer supported.

2 · Architecture at a glance

The SDK follows three layers:

Carrier  ──►  Consignment  ──►  MyParcelCollection
( ID/name)    (one parcel)      (batch + label I/O)

• Carrier — a static model per carrier with ID, NAME and matching Consignment class. See src/Model/Carrier.
• Consignment — all data for a single parcel (sender, recipient, options, physical properties). Carrier-specific subclasses (e.g. PostNLConsignment) determine which delivery_type, package_type and shipment_option combinations are allowed. See src/Model/Consignment.
• MyParcelCollection — collects consignments, talks to the API (POST /shipments, /shipment_labels, /track_traces), generates PDF labels and handles multi-collo. See src/Helper/MyParcelCollection.php.

Top-level namespaces:

3 · Authentication

The SDK authenticates per request with a shop API key (Basic auth). There is no OAuth flow at SDK level — the SDK handles any token exchange internally if the API requires it.

$apiKey = getenv('MYPARCEL_API_KEY'); // base64-encoded shop key from the backoffice

How the key is used:

use MyParcelNL\Sdk\Factory\ConsignmentFactory;
use MyParcelNL\Sdk\Model\Carrier\CarrierPostNL;

$consignment = ConsignmentFactory::createByCarrierId(CarrierPostNL::ID)
    ->setApiKey($apiKey);

setApiKey() exists on every consignment, so mixing keys within one collection is possible — useful for multi-shop integrations.

User agent (required for integrations)

Plugins and custom integrations must identify themselves — without this, debugging is impossible and MyParcel cannot trace the source of an issue.

$consignment->setUserAgentForProposition('CustomShop', '2.4.1');

setUserAgentForProposition(string $proposition, ?string $version) is the new API; setUserAgent() is deprecated and will be removed in the next major. The SDK appends MyParcelNL-SDK/<sdkVersion> and php/<phpVersion> to the header itself.

4 · Quickstart — first shipment

One consignment, one label, A6 PDF on disk.

<?php
require 'vendor/autoload.php';

use MyParcelNL\Sdk\Factory\ConsignmentFactory;
use MyParcelNL\Sdk\Helper\MyParcelCollection;
use MyParcelNL\Sdk\Model\Carrier\CarrierPostNL;
use MyParcelNL\Sdk\Model\Consignment\AbstractConsignment;

$apiKey = getenv('MYPARCEL_API_KEY');

$consignment = (ConsignmentFactory::createByCarrierId(CarrierPostNL::ID))
    ->setApiKey($apiKey)
    ->setReferenceIdentifier('ORDER-2026-01042')
    ->setCountry(AbstractConsignment::CC_NL)
    ->setPerson('J. de Vries')
    ->setFullStreet('Antwoordnummer 42')
    ->setPostalCode('1012AB')
    ->setCity('Amsterdam')
    ->setEmail('test@example.com')
    ->setPackageType(AbstractConsignment::PACKAGE_TYPE_PACKAGE)
    ->setLabelDescription('Order #146');

(new MyParcelCollection())
    ->addConsignment($consignment)
    ->setUserAgentForProposition('CustomShop', '2.4.1')
    ->setPdfOfLabels()           // POST /shipments + GET /shipment_labels
    ->downloadPdfOfLabels();     // streams the PDF to the browser

What happens under the hood: the collection calls POST /shipments, gets consignment IDs back, then fetches labels via GET /shipment_labels/{ids} and stitches them into one PDF.

5 · Builder conventions

• Fluent setters. Every setter returns $this — chain them.
• Constants over strings. PACKAGE_TYPE_PACKAGE (= 1) and DELIVERY_TYPE_STANDARD (= 2) read better than magic numbers and don't break if the API extends its ranges.
• Validators run automatically. Each carrier has a *ConsignmentValidator that enforces allowed combinations. Calling setSignature(true) on a carrier that doesn't support it throws an InvalidConsignmentException.
• getAllowed*() methods. Ask a consignment which options are valid before using them:

  $consignment->getAllowedDeliveryTypes();   // ['morning','standard','evening','pickup']
  $consignment->getAllowedPackageTypes();    // ['package','mailbox','letter','digital_stamp','package_small']
  $consignment->getAllowedShipmentOptions(); // ['age_check','insurance','large_format', ...]
  

6 · Carriers

Every carrier has an ID (numeric, used by the API) and a NAME (slug, used by name-based factory calls).

use MyParcelNL\Sdk\Factory\ConsignmentFactory;

ConsignmentFactory::createByCarrierId(2);            // bpost
ConsignmentFactory::createByCarrierName('dhlforyou'); // DHL For You

7 · Consignment options

Package types

The type determines size rules and which shipment options are available. It varies per carrier; check getAllowedPackageTypes().

Delivery types

Pickup shipments need a PickupLocation — set it via setPickupLocation(new PickupLocation([...])).

Shipment options

Boolean extras on top of the base service.

Insurance

Amounts are in euro cents. Get the allowed maxima per country with getInsurancePossibilities(?string $cc):

$consignment->getInsurancePossibilities('NL'); // [0, 100, 250, 500, ..., 50000]
$consignment->setInsurance(50000);             // €500

Multi-collo (one label flow for multiple parcels)

For shipments that physically consist of multiple parcels but logistically belong together:

(new MyParcelCollection())
    ->addMultiCollo($consignment, 3)        // 1 main parcel + 2 follow-up parcels
    ->setPdfOfLabels()
    ->downloadPdfOfLabels();

Only works on carriers that offer multi-collo (getAllowedExtraOptions() contains 'multi_collo').

8 · MyParcelCollection — batch API

MyParcelCollection is a Laravel-style collection with SDK-specific methods. The main public API:

Order of calls in the typical workflow:

addConsignment*() → setLinkOfLabels() or setPdfOfLabels()
                 → downloadPdfOfLabels() or getLabelPdf()
                 → (optional) fetchTrackTraceData()

setPdfOfLabels() and setLinkOfLabels() internally trigger createConcepts() if it hasn't run yet — you rarely need to call it explicitly.

9 · Labels and printing

A6 versus A4

The default paper format is A6. For A4 sheets with multiple labels per page, pass a position:

// A6, one label per page
$collection->setPdfOfLabels()->downloadPdfOfLabels();

// A4, label at position 1 (top-left), 2 (top-right), 3 (bottom-left), 4 (bottom-right)
$collection->setPdfOfLabels(2)->downloadPdfOfLabels();

// A4, starting from position 1, auto-fills the sheet
$collection->setPdfOfLabels(1)->downloadPdfOfLabels();

Positions 1–4 only matter on A4. On A6 the argument is ignored.

Direct printing (v10.6.0+)

For shops with a connected label printer in the MyParcel backoffice:

$collection
    ->setLinkOfLabels()
    ->printDirect('printer-group-uuid-here');

Get the printerGroupId from the backoffice — Settings → Printers. Direct printing doesn't request a PDF on disk; the print server is assigned the shipment directly.

Share a label link without downloading the PDF

$url = $collection->setLinkOfLabels()->getLinkOfLabels();
// signed URL, short-lived — suitable for an email or UI link

10 · Track & Trace

First hydrate the consignments, then fetch T&T data:

$collection
    ->setLatestData()         // status + barcode
    ->fetchTrackTraceData();  // history events

foreach ($collection->getConsignments() as $c) {
    echo $c->getBarcode();
    echo $c->getBarcodeUrl(
        $c->getBarcode(),
        $c->getPostalCode(),
        $c->getCountry()
    );
}

getBarcodeUrl() returns the public track-and-trace URL. Safe to drop into an email to the end customer.

Status constants on AbstractConsignment:

11 · Query and retrieve

By consignment ID

$collection = (new MyParcelCollection())
    ->addConsignmentByConsignmentIds([12345678, 12345679], $apiKey)
    ->setLatestData();

By reference identifier

$collection = (new MyParcelCollection())
    ->addConsignmentByReferenceIds(['ORDER-2026-01042'], $apiKey)
    ->setLatestData();

Filter / search

$collection = MyParcelCollection::query($apiKey, [
    'q'      => 'de Vries',
    'status' => AbstractConsignment::STATUS_CONCEPT,
    'from'   => '2026-04-01 00:00:00',
    'to'     => '2026-05-01 00:00:00',
    'size'   => 100,
]);

Valid filter keys mirror the GET /shipments endpoint parameters in the API reference. The SDK passes them straight through.

12 · Returns

Return-in-the-box (label travels with the original shipment)

$consignment->setReturn(true);
$collection->addConsignment($consignment);

The return label sits on page 2 of the PDF. The customer sticks it on the box and ships it back.

Printerless return (customer scans a QR code at PostNL)

$consignment->setPrinterlessReturn(true);

No printed label — the customer gets a QR code in the portal/email. Only works on carriers that support it.

Stand-alone return shipment

For returns unrelated to an existing shipment (e.g. an RMA after 30 days):

$collection
    ->addConsignmentByConsignmentIds([$originalId], $apiKey)
    ->generateReturnConsignments(
        sendMail: true,
        modifier: function ($returnConsignment) {
            $returnConsignment->setLabelDescription('RMA-2026-7712');
        }
    );

sendMail: true triggers the standard MyParcel return email to the recipient with the QR code or label link.

13 · Order API (Fulfilment)

For accounts with a fulfilment contract: instead of creating labels directly, you place an order that later flows through the fulfilment pipeline.

use MyParcelNL\Sdk\Collection\Fulfilment\OrderCollection;
use MyParcelNL\Sdk\Model\Fulfilment\Order;
use MyParcelNL\Sdk\Model\Fulfilment\OrderLine;
use MyParcelNL\Sdk\Model\Fulfilment\Product;
use MyParcelNL\Sdk\Model\Recipient;

$order = (new Order())
    ->setExternalIdentifier('ORDER-2026-01042')
    ->setRecipient(new Recipient([
        'cc'         => 'NL',
        'person'     => 'J. de Vries',
        'street'     => 'Antwoordnummer',
        'number'     => '42',
        'postalCode' => '1012AB',
        'city'       => 'Amsterdam',
    ]))
    ->setOrderLines([
        (new OrderLine())
            ->setQuantity(2)
            ->setProduct(
                (new Product())
                    ->setSku('SKU-7712')
                    ->setName('Linen bag, blue')
                    ->setEan('8712345678905')
            ),
    ]);

(new OrderCollection())
    ->setApiKey($apiKey)
    ->push($order)
    ->save(); // POST /fulfilment/orders

Order notes

Attach fulfilment instructions or CS notes to an order:

use MyParcelNL\Sdk\Collection\Fulfilment\OrderNotesCollection;
use MyParcelNL\Sdk\Model\Fulfilment\OrderNote;

(new OrderNotesCollection())
    ->setApiKey($apiKey)
    ->push(
        (new OrderNote())
            ->setOrderUuid($order->getUuid())
            ->setNote('Add gift wrap')
            ->setAuthor('webshop')
    )
    ->save(); // POST /fulfilment/orders/{id}/notes

14 · Webhooks

The SDK doesn't ship a webhook server (that's your application), but it does include models to manage subscriptions. See Webhooks for end-to-end examples.

// pseudo: list all existing subscriptions
MyParcelRequest::sendRequest('GET', 'webhook_subscriptions');

Available event types are kept up to date in the API reference.

15 · Exceptions

Everything sits under MyParcelNL\Sdk\Exception\:

On top of these SDK-specific exceptions you may also see generic PHP exceptions — InvalidArgumentException (wrong type passed) and BadMethodCallException (no setter for that key).

use MyParcelNL\Sdk\Exception\ApiException;
use MyParcelNL\Sdk\Exception\InvalidConsignmentException;

try {
    $collection->setPdfOfLabels()->downloadPdfOfLabels();
} catch (InvalidConsignmentException $e) {
    // recoverable — log + correct the consignment
} catch (ApiException $e) {
    // network/backend — retry-with-backoff or queue
}

16 · Testing against the SDK

The SDK uses PHPUnit + Mockery in its own tests. For your integration tests:

• Unit level — mock the MyParcelCurl helper or the entire MyParcelCollection (addConsignment is fluent → easy to mock).
• Integration level — use a sandbox account and the real API. There is no public sandbox URL; request a test shop via support@myparcel.nl.
• Snapshot tests on label bytes are not stable — PDF stitching uses timestamps. Test the business logic, not the bytes.

composer require --dev mockery/mockery phpunit/phpunit
./vendor/bin/phpunit

17 · Migrating from older versions

From the old MyParcel\Sdk namespace

The pre-v8 SDK used MyParcel\Sdk\ without NL. Find-and-replace:

MyParcel\Sdk\   →   MyParcelNL\Sdk\

PSR-4 takes care of the rest — no further autoload config needed.

To v10.x

Main breaks per minor:

Full changelog: github.com/myparcelnl/sdk/blob/main/CHANGELOG.md ↗.

18 · Contributing and support

• Source — github.com/myparcelnl/sdk ↗ (MIT)
• Issues — open an issue with PHP version, SDK version and a minimal reproduction.
• Slack — #sdk in myparcel-dev.slack.com ↗
• Email — support@myparcel.nl

PR guidelines: branch from main, write tests with Mockery (no live HTTP), commits follow Conventional Commits.