Shipments

Shipments are at the core of our services. Get shipments and their data to inform your customers about them.

The shipment model

The shipment model contains all the information about the shipments used in your proposition.

Properties

Name
id
Type
string
Description
A generated unique identifier for the shipment.
Name
shipmentDate
Type
date
Description
The date on wich the shipment was shipped
Name
trackingCode
Type
string
Description
The trackingCode for the shipment
Name
shippingAgent
Type
string
Description
The shipping agent that handled the shipment.
Name
shippingService
Type
string
Description
The code for the service of the shipping agent.
Name
trackingLink
Type
string
Description
The trackingLink for the shipment. Share this with your customer.
Name
lines
Type
array
Description
The collection containing the shipment lines for this shipment. Refer to the shipmentLine model to see the properties for a line.
Name
packages
Type
array
Description
The collection of physical packages that make up this shipment (one entry per box, multi-colli aware). Refer to the shipmentPackage model to see the properties.
Name
outbound
Type
object
Description
The outbound this shipment belongs to. Refer to the outbound model to see the properties for a outbound.

GET/fulfilment/v4/shipments?skip=:skip&take=:take

Retrieve a shipment

This endpoint allows you to retrieve a shipment by providing the id. The id is supplied in the webhook for shipment-shipped

Required attributes

Name
id
Type
string
Description
Path parameter representing the id of the shipment.

Optional arguments

Name
include
Type
enum
Description
The related record to include. Valid values: lines, packages, outbound
Name
format
Type
enum
Description
The format of the response. Valid values: json, pdf. Defaults to json. When pdf, the response body is the raw packing-slip PDF (see Retrieve a shipment's packing slip).

Request

GET

/fulfilment/v4/shipments/:id

curl --location https://partner.punt-uit.nl/api/fulfilment/v4/shipments/cloft5bsn0001kw08wtrxbt60 \
  --header "Authorization: Bearer {token}"

Response

  {
    "id": "cloft5bsn0001kw08wtrxbt60",
    "shipmentDate": "2023-11-01",
    "trackingCode": "DOT11291",
    "shippingAgent": "PUNTUIT",
    "shippingService": "PICKUP",
    "trackingLink": "",
    "lines": [
        {
            "quantity": 1,
            "outboundRef": "249060670",
            "outboundLineRef": "492843012",
            "sku": "17177"
        }
    ],
    "packages": [
        {
            "lineNo": 1,
            "trackingCode": "3SDEVC9029881",
            "trackingLink": "http://postnl.nl/tracktrace/?L=NL&B=3SDEVC9029881&P=7814VN&D=NL&T=C",
            "packageType": "BOX",
            "boxNo": "BOX04317366",
            "batchId": null,
            "batchTrackingCode": null,
            "batchTrackingLink": null,
            "batchShippingAgent": null,
            "batchShippingService": null
        },
        {
            "lineNo": 2,
            "trackingCode": "3SDEVC9029882",
            "trackingLink": "http://postnl.nl/tracktrace/?L=NL&B=3SDEVC9029882&P=7814VN&D=NL&T=C",
            "packageType": "BOX",
            "boxNo": "BOX04317368",
            "batchId": null,
            "batchTrackingCode": null,
            "batchTrackingLink": null,
            "batchShippingAgent": null,
            "batchShippingService": null
        }
    ],
    "outbound": {
        "ref": "249060670",
        "orderRef": "ORD1159861",
        "message": "",
        "shippingAdvice": "complete",
        "shipToName": "Punt-uit",
        "shipToContact": "Paul Katuin",
        "shipToAddressLine1": "Nieuw-Amsterdamsestraat 40",
        "shipToAddressLine2": "",
        "shipToCity": "Emmen",
        "shipToCountryCode": "NL",
        "shipToPostCode": "7814 VA",
        "shippingContactName": "Paul Katuin",
        "shippingContactEmail": "financieel@punt-uit.nl",
        "shippingContactPhonenumber": "",
        "shippingContactAddress": "Nieuw-Amsterdamsestraat 40",
        "shippingContactPostCode": "7814 VA",
        "shippingContactCity": "Emmen",
        "shippingContactCountryCode": "NL",
        "shipmentMethodCode": "PUNTUIT-PICKUP-DAP",
        "deliveryDate": null,
        "status": "picked_up"
    }
 }

For a shipment that traveled as part of a consolidation batch, each package's batch* fields are populated with the carrier-level tracking of the consolidation container it sat on. Packages on the same shipment may belong to different batches (one shipment split across two pallets):

Response — consolidated

  {
    "id": "cloft5bsn0001kw08wtrxbt60",
    "shipmentDate": "2026-04-27",
    "trackingCode": "3SDEVC9029879",
    "shippingAgent": "POSTNL",
    "shippingService": "3610",
    "trackingLink": "http://postnl.nl/tracktrace/?L=NL&B=3SDEVC9029879&P=7814VN&D=NL&T=C",
    "packages": [
        {
            "lineNo": 1,
            "trackingCode": null,
            "trackingLink": null,
            "packageType": "BOX",
            "boxNo": "BOX04317352",
            "batchId": "CON0000022:1",
            "batchTrackingCode": "3SDEVC9029879",
            "batchTrackingLink": "http://postnl.nl/tracktrace/?L=NL&B=3SDEVC9029879&P=7814VN&D=NL&T=C",
            "batchShippingAgent": "POSTNL",
            "batchShippingService": "3610"
        }
    ]
 }

GET/fulfilment/v4/shipments/:id?format=pdf

Retrieve a shipment's packing slip

Retrieve the packing slip (pakbon) for a shipment as a PDF. Request the PDF either by setting ?format=pdf or by sending an Accept: application/pdf header. The response body is the raw PDF bytes with Content-Type: application/pdf.

Packing slips are immutable once a shipment has shipped, so the response is served with Cache-Control: private, max-age=31536000, immutable — safe to cache and store on your side.

Required attributes

Name
id
Type
string
Description
Path parameter representing the id of the shipment.

Response

200 OK — body is the PDF, Content-Disposition: attachment; filename="packing-slip-{id}.pdf".
404 Not Found — the shipment does not exist or no packing slip is available for it.
502 Bad Gateway — the upstream system failed to return the PDF.

Request

GET

/fulfilment/v4/shipments/:id?format=pdf

curl --location https://partner.punt-uit.nl/api/fulfilment/v4/shipments/cloft5bsn0001kw08wtrxbt60?format=pdf \
  --header "Authorization: Bearer {token}" \
  --output packing-slip.pdf

The shipmentLine model

The shipmentLine model contains all the information about shipmentLines, such as their sku, outboundRef, outboundLineRef and quantity.

Properties

Name
sku
Type
string
Description
The unique sku for the product that has been shipped.
Name
outboundRef
Type
string
Description
Your unique reference for the outbound.
Name
outboundLineRef
Type
string
Description
Your unique reference for the outboundLine
Name
quantity
Type
integer
Description
The number of items that have been shipped.

The shipmentPackage model

The shipmentPackage model represents one physical package (box, parcel, …) that is part of a shipment. A multi-colli shipment has one entry per package; a single-package shipment has one. When the shipment travels as part of a consolidation batch, the batch* fields are populated with the carrier-level tracking of the consolidation container the package was placed on.

Properties

Name
lineNo
Type
integer
Description
The sequence number of this package within the shipment, starting at 1.
Name
trackingCode
Type
string
Description
The carrier tracking code for this individual package, when the carrier issues per-package codes (e.g. PostNL multi-colli). May be null for shipments without per-package tracking.
Name
trackingLink
Type
string
Description
The carrier tracking URL for this individual package, when available.
Name
packageType
Type
string
Description
The type of the package, e.g. BOX, PALLET.
Name
boxNo
Type
string
Description
A reference identifier for the physical box. Useful in disputes or operational queries.
Name
batchId
Type
string
Description
The identifier of the physical pallet this package was placed on, when shipped via consolidation. Format is {consolidationOrderNo}:{lineNo} (e.g. CON0000022:2), so two pallets on the same consolidation booking are distinguishable. Packages on the same physical pallet share this value. null for non-consolidated shipments.
Name
batchTrackingCode
Type
string
Description
The carrier tracking code printed on the physical pallet this package was placed on. Packages on the same pallet share this value; packages on sibling pallets within the same consolidation booking get distinct codes (multi-colli).
Name
batchTrackingLink
Type
string
Description
The carrier tracking URL for the physical pallet, when issued by the carrier.
Name
batchShippingAgent
Type
string
Description
The shipping agent for the consolidation container (e.g. POSTNL).
Name
batchShippingService
Type
string
Description
The shipping agent service code for the consolidation container.

Shipments

The shipment model

Properties

List your shipments

Optional arguments

Request

Response

Retrieve a shipment

Required attributes

Optional arguments

Request

Response

Response — consolidated

Retrieve a shipment's packing slip

Required attributes

Response

Request

The shipmentLine model

Properties

The shipmentPackage model

Properties