REST API introduction (1.0)

Download OpenAPI specification:

URL for API requests

https://api.paazl.com/

Optional keys

Some of the optional key-value pairs have a default value. Where this is the case, the default values will be indicated.

You can leave out optional keys from requests. If you leave out an optional key, it will not be included in the response.

API client

You can generate an API client using Paazl's REST API specification. See the online help article titled "Generating an API client" for more information.

Paazl authentication

Paazl uses a three-legged OAuth 2.0 authentication process in which the API Secret (private key) is only known to the webshop. Webshop customers never have access to that key. However, they do have access the API Key (public key). See the online help article titled "Authentication & Authorization" for an explanation of how to generate these keys in the Paazl web app.

In Swagger, you authorize a call using the Authorize button. After clicking this button, you enter a string with either the format "Bearer api_key" or the format "Bearer api_key:api_secret" depending on the endpoint method.

Calls requiring "Bearer api_key":

• POST shippingOptions

• POST pickupLocations

• POST checkout

Example:"Bearer sI3flYhflh"

Calls requiring "Bearer api_key:api_secret":

• POST token

• GET checkout

• POST order

• PUT order

• DELETE order

• POST shipments

• GET shipments

Example:"Bearer sI3flYhflh:sdHlHkyunLKsoI94luilIlndD"

Checkout

Checkout endpoint

Gets checkout session data.

Gets your reference for a checkout session, along with the customer's preferred delivery date, country code, postal code, preferred shipping option or pickup location, and the order's shipping rate.

Authorizations:
Authorization
query Parameters
reference
required
string

Your reference for the checkout session whose details you want to retrieve. The reference is the one you used when you created an access token with the token endpoint.

Note! If the reference value provided already exists, the existing session will be replaced with a new session.

Example:https://api.paazl.com/checkout?reference=AA01234

Responses

Response samples

Content type
<checkoutInfo>
	<consigneeCountryCode>string</consigneeCountryCode>
	<consigneePostalCode>string</consigneePostalCode>
	<deliveryType>PICKUP_LOCATION</deliveryType>
	<notificationEmailAddress>string</notificationEmailAddress>
	<notificationPhoneNumber>string</notificationPhoneNumber>
	<pickupDate>2026-10-07</pickupDate>
	<selectedPickupLocation>
		<accountNumber>string</accountNumber>
		<address>
			<city>string</city>
			<country>string</country>
			<postalCode>string</postalCode>
			<province>string</province>
			<street>string</street>
			<streetNumber>0</streetNumber>
			<streetNumberSuffix>string</streetNumberSuffix>
		</address>
		<code>string</code>
		<coordinates>
			<latitude>0</latitude>
			<longitude>0</longitude>
		</coordinates>
		<distance>0</distance>
		<name>string</name>
		<openingTimes>
			<openingTime>
				<alwaysOpen>true</alwaysOpen>
				<businessHours>
					<businessHour>
						<from>string</from>
						<to>string</to>
					</businessHour>
				</businessHours>
				<day>MONDAY</day>
			</openingTime>
		</openingTimes>
	</selectedPickupLocation>
	<preferredDeliveryDate>2026-10-07</preferredDeliveryDate>
	<reference>string</reference>
	<selectedShippingOption>
		<carrier>
			<description>string</description>
			<name>string</name>
		</carrier>
		<deliveryDates>
			<deliveryDate>
				<deliveryDate>2026-10-07</deliveryDate>
				<pickupDate>2026-10-07</pickupDate>
				<cutoffTime>string</cutoffTime>
				<timeRange>
					<end>string</end>
					<start>string</start>
				</timeRange>
				<rate>0</rate>
				<rateReason>GREEN</rateReason>
			</deliveryDate>
		</deliveryDates>
		<deliveryWindow>
			<end>string</end>
			<start>string</start>
		</deliveryWindow>
		<description>string</description>
		<estimatedDeliveryRange>
			<earliestDate>2026-10-07</earliestDate>
			<latestDate>2026-10-07</latestDate>
			<max>0</max>
			<min>0</min>
		</estimatedDeliveryRange>
		<identifier>string</identifier>
		<name>string</name>
		<rate>0</rate>
		<tags>
			<tag>PARCEL_LOCKER</tag>
		</tags>
		<carrierMetadataArray>
			<carrierMetadata>
				<name>string</name>
				<values>
					<value>
					</value>
				</values>
			</carrierMetadata>
		</carrierMetadataArray>
		<metadataArray>
			<metadata>
				<name>string</name>
				<value>string</value>
			</metadata>
		</metadataArray>
	</selectedShippingOption>
	<token>3fa85f64-5717-4562-b3fc-2c963f66afa6</token>
	<webshopId>0</webshopId>
</checkoutInfo>

Saves checkout session data.

Saves the most important information of a specific checkout session to the Paazl database. The information will be kept for 30 days.

If the checkout data is successfully saved, the call simply returns HTTP Status 200 OK.

Authorizations:
Authorization
Request Body schema:
required
object (PickupLocationSelection)

Contains details of the pickup location that your customer selected at checkout.

preferredDeliveryDate
string <date>

The day of the week on which customers want their order delivered.

required
object (ShippingOptionSelection)

Contains details of the shipping option that your customer selected at checkout.

token
required
string <uuid>

The access token returned by the token endpoint.

Because you gave the session a reference code when requesting the token, Paazl automatically knows which session the token refers to.

Example: token:"4f7c7af4-a379-4d5e-8ccf-807f4ba97a52"

Responses

Request samples

Content type
<saveCheckout>
	<pickupLocation>
		<accountNumber>string</accountNumber>
		<code>string</code>
	</pickupLocation>
	<preferredDeliveryDate>2026-10-07</preferredDeliveryDate>
	<shippingOption>
		<identifier>string</identifier>
	</shippingOption>
	<token>3fa85f64-5717-4562-b3fc-2c963f66afa6</token>
</saveCheckout>

Returns access token.

Returns an access token for a checkout session. This enables the Paazl checkout widget to access Paazl resources.

See Authentication and authorization for an explanation of how Paazl authentication and authorization works.

Authorizations:
Authorization
Request Body schema:
required
reference
required
string

Your reference for the checkout session whose details you want to retrieve. The reference is the one you used when you created an access token with the "/checkout/token" endpoint.

Note! If the reference value you provide already exists, Paazl will replace the existing session with a new session.

Example: reference:"order1234"

Responses

Request samples

Content type
<reference>
	<reference>string</reference>
</reference>

Response samples

Content type
<checkoutToken>
	<token>3fa85f64-5717-4562-b3fc-2c963f66afa6</token>
</checkoutToken>

Order

Order endpoint

Saves order information.

Saves an order's most important information to the Paazl database once a customer has paid for his/her purchase. You commonly implement POST order when you want to make use of Paazl's label printing and track & trace notification functionality. You can also use it with an OMS or WMS.

If the order information is successfully saved, the call simply returns HTTP Status 200 OK.


Note!

The POST order method lets you to save shipping address information (required), as well as sender address and return address information (optional). Whenever you specify an address, you can either fill street or both street and houseNumber separately or you can specify them as a single string using streetLines. Whether you use one or the other depends on the requirements of the carrier. Paazl applies the following logic to these attributes:

• If you fill street and houseNumber, they take priority over a filled streetLines

• If you fill street or houseNumber but not both, then a filled streetLines takes priority

• If you fill street but houseNumber and streetLines are empty, street takes priority

• If you fill street or houseNumber but not both, and streetLines is empty, an error will be thrown

Authorizations:
Authorization
Request Body schema:
required
additionalInstruction
string

Additional instructions for the delivery of an order.

Example: additionalInstruction:"Call before delivery"

required
object (Contact)

Contains details of the party to which an order is shipped.

object (CustomsValue)

The total monetary value for customs purposes.

object (InsuredValue)

The amount for which this is insured by the carrier against loss, damage or accident during transport.

object (CodValue)

The amount that a consignee has to pay before receiving the "Cash On Delivery" consignment.

description
string

A general description of the contents of a shipment.

Example: description:"Socks"

requestedDeliveryDate
string <date>

The date on which a customer has requested that an order be delivered.

Format: "YYYY-MM-DD"

Example: requestedDeliveryDate:2019-18-02

Array of objects (Product)

Contains objects representing the products making up a order.

reference
required
string

Your own order reference for a purchase transaction. For security reasons, the following special characters are not allowed: \ and /.

Note! The order reference must be unique within the webshop.

Example: reference:"myOrderReference-00123"

invoiceNumber
string

The invoice number of an order.

This is sometimes required by carriers for international shipments.

Example: invoiceNumber:"invnr-1234567890"

invoiceDate
string <date>

The invoice date of an order.

This is the date on the invoice, as used by some carriers for international shipments for customs.

Format: "YYYY-MM-DD"

Example: invoiceDate:2021-02-15

object (ShopOrderParty)

Contains the details of an address to which an order is returned.

object (ShopOrderParty)

Contains the details of the address from which an order is shipped.

required
object (ShopOrderShipping)

Contains information on the shipping option selected by a customer.

weight
number <double>

The total weight in kilograms (kg) of an order, including packaging for shipping.

Example: weight:10.12

object
object

Responses

Request samples

Content type
<shopOrder>
	<additionalInstruction>string</additionalInstruction>
	<consignee>
		<companyName>string</companyName>
		<eoriNumber>string</eoriNumber>
		<vatNumber>string</vatNumber>
		<email>string</email>
		<name>string</name>
		<other>string</other>
		<phone>string</phone>
		<locale>string</locale>
		<consigneeType>BUSINESS</consigneeType>
		<address>
			<city>string</city>
			<country>string</country>
			<postalCode>string</postalCode>
			<province>string</province>
			<street>string</street>
			<streetLines>
				<streetLine>string</streetLine>
			</streetLines>
			<houseNumber>0</houseNumber>
			<houseNumberExtension>string</houseNumberExtension>
		</address>
	</consignee>
	<customsValue>
		<value>0</value>
		<currency>string</currency>
	</customsValue>
	<insuredValue>
		<value>0</value>
		<currency>string</currency>
	</insuredValue>
	<codValue>
		<value>0</value>
		<currency>string</currency>
	</codValue>
	<description>string</description>
	<requestedDeliveryDate>2026-10-07</requestedDeliveryDate>
	<products>
		<product>
			<height>0</height>
			<length>0</length>
			<unitPrice>
				<value>0</value>
				<currency>string</currency>
			</unitPrice>
			<quantity>0</quantity>
			<volume>0</volume>
			<weight>0</weight>
			<width>0</width>
			<countryOfManufacture>string</countryOfManufacture>
			<description>string</description>
			<hsTariffCode>string</hsTariffCode>
			<skuCode>string</skuCode>
		</product>
	</products>
	<reference>string</reference>
	<invoiceNumber>string</invoiceNumber>
	<invoiceDate>2026-10-07</invoiceDate>
	<return>
		<name>string</name>
		<address>
			<city>string</city>
			<country>string</country>
			<postalCode>string</postalCode>
			<province>string</province>
			<street>string</street>
			<streetLines>
				<streetLine>string</streetLine>
			</streetLines>
			<houseNumber>0</houseNumber>
			<houseNumberExtension>string</houseNumberExtension>
		</address>
	</return>
	<sender>
		<name>string</name>
		<address>
			<city>string</city>
			<country>string</country>
			<postalCode>string</postalCode>
			<province>string</province>
			<street>string</street>
			<streetLines>
				<streetLine>string</streetLine>
			</streetLines>
			<houseNumber>0</houseNumber>
			<houseNumberExtension>string</houseNumberExtension>
		</address>
	</sender>
	<shipping>
		<option>string</option>
		<pickupLocation>
			<accountNumber>string</accountNumber>
			<code>string</code>
		</pickupLocation>
		<contract>string</contract>
		<returnContract>string</returnContract>
		<return>
			<reason>COURTESY_RETURN_LABEL</reason>
			<description>string</description>
		</return>
		<packageCount>0</packageCount>
		<multiPackageShipment>true</multiPackageShipment>
	</shipping>
	<weight>0</weight>
	<customs>
		<incoterm>string</incoterm>
		<reasonForExport>string</reasonForExport>
		<declarationStatement>string</declarationStatement>
		<comment>string</comment>
		<customsValue>
			<value>0</value>
			<currency>string</currency>
		</customsValue>
		<importer>
			<payment>string</payment>
			<eoriNumber>string</eoriNumber>
			<vatNumber>string</vatNumber>
			<accountNumber>string</accountNumber>
			<name>string</name>
			<address>
				<city>string</city>
				<country>string</country>
				<postalCode>string</postalCode>
				<province>string</province>
				<street>string</street>
				<streetLines>
					<streetLine>string</streetLine>
				</streetLines>
				<houseNumber>0</houseNumber>
				<houseNumberExtension>string</houseNumberExtension>
			</address>
			<vendorCollectIdTypeCode>UNKNOWN_OTHER</vendorCollectIdTypeCode>
			<vendorCollectIdNumber>string</vendorCollectIdNumber>
			<consigneeType>BUSINESS</consigneeType>
		</importer>
	</customs>
	<shipper>
		<payment>string</payment>
		<eoriNumber>string</eoriNumber>
		<vatNumber>string</vatNumber>
		<accountNumber>string</accountNumber>
		<name>string</name>
		<address>
			<city>string</city>
			<country>string</country>
			<postalCode>string</postalCode>
			<province>string</province>
			<street>string</street>
			<streetLines>
				<streetLine>string</streetLine>
			</streetLines>
			<houseNumber>0</houseNumber>
			<houseNumberExtension>string</houseNumberExtension>
		</address>
		<shipperType>BUSINESS</shipperType>
	</shipper>
</shopOrder>

Modifies order information.

Modifies the information of an order with a specific reference in the Paazl database. The method overwrites the order so the same attribute restrictions apply as for the POST order method.

If the order data is successfully modified, the call simply returns HTTP Status 200 OK.

Note!

The PUT order method lets you to save shipping address information (required), as well as sender address and return address information (optional). Whenever you specify an address, you can either fill street and houseNumber separately or you can specify both as a single string using streetLines. Whether you use one or the other depends on the requirements of the carrier. Paazl applies the following logic to these attributes:

• If you fill street and houseNumber, they take priority over a filled streetLines

• If you fill street or houseNumber but not both, then a filled streetLines takes priority

• If you fill street or houseNumber but not both, and streetLines is empty, an error will be thrown

Authorizations:
Authorization
Request Body schema:
required
additionalInstruction
string

Additional instructions for the delivery of an order.

Example: additionalInstruction:"Call before delivery"

required
object (Contact)

Contains details of the party to which an order is shipped.

object (CustomsValue)

The total monetary value for customs purposes.

object (InsuredValue)

The amount for which this is insured by the carrier against loss, damage or accident during transport.

object (CodValue)

The amount that a consignee has to pay before receiving the "Cash On Delivery" consignment.

description
string

A general description of the contents of a shipment.

Example: description:"Socks"

requestedDeliveryDate
string <date>

The date on which a customer has requested that an order be delivered.

Format: "YYYY-MM-DD"

Example: requestedDeliveryDate:2019-18-02

Array of objects (Product)

Contains objects representing the products making up a order.

reference
required
string

Your own order reference for a purchase transaction. For security reasons, the following special characters are not allowed: \ and /.

Note! The order reference must be unique within the webshop.

Example: reference:"myOrderReference-00123"

invoiceNumber
string

The invoice number of an order.

This is sometimes required by carriers for international shipments.

Example: invoiceNumber:"invnr-1234567890"

invoiceDate
string <date>

The invoice date of an order.

This is the date on the invoice, as used by some carriers for international shipments for customs.

Format: "YYYY-MM-DD"

Example: invoiceDate:2021-02-15

object (ShopOrderParty)

Contains the details of an address to which an order is returned.

object (ShopOrderParty)

Contains the details of the address from which an order is shipped.

required
object (ShopOrderShipping)

Contains information on the shipping option selected by a customer.

weight
number <double>

The total weight in kilograms (kg) of an order, including packaging for shipping.

Example: weight:10.12

object
object

Responses

Request samples

Content type
<shopOrder>
	<additionalInstruction>string</additionalInstruction>
	<consignee>
		<companyName>string</companyName>
		<eoriNumber>string</eoriNumber>
		<vatNumber>string</vatNumber>
		<email>string</email>
		<name>string</name>
		<other>string</other>
		<phone>string</phone>
		<locale>string</locale>
		<consigneeType>BUSINESS</consigneeType>
		<address>
			<city>string</city>
			<country>string</country>
			<postalCode>string</postalCode>
			<province>string</province>
			<street>string</street>
			<streetLines>
				<streetLine>string</streetLine>
			</streetLines>
			<houseNumber>0</houseNumber>
			<houseNumberExtension>string</houseNumberExtension>
		</address>
	</consignee>
	<customsValue>
		<value>0</value>
		<currency>string</currency>
	</customsValue>
	<insuredValue>
		<value>0</value>
		<currency>string</currency>
	</insuredValue>
	<codValue>
		<value>0</value>
		<currency>string</currency>
	</codValue>
	<description>string</description>
	<requestedDeliveryDate>2026-10-07</requestedDeliveryDate>
	<products>
		<product>
			<height>0</height>
			<length>0</length>
			<unitPrice>
				<value>0</value>
				<currency>string</currency>
			</unitPrice>
			<quantity>0</quantity>
			<volume>0</volume>
			<weight>0</weight>
			<width>0</width>
			<countryOfManufacture>string</countryOfManufacture>
			<description>string</description>
			<hsTariffCode>string</hsTariffCode>
			<skuCode>string</skuCode>
		</product>
	</products>
	<reference>string</reference>
	<invoiceNumber>string</invoiceNumber>
	<invoiceDate>2026-10-07</invoiceDate>
	<return>
		<name>string</name>
		<address>
			<city>string</city>
			<country>string</country>
			<postalCode>string</postalCode>
			<province>string</province>
			<street>string</street>
			<streetLines>
				<streetLine>string</streetLine>
			</streetLines>
			<houseNumber>0</houseNumber>
			<houseNumberExtension>string</houseNumberExtension>
		</address>
	</return>
	<sender>
		<name>string</name>
		<address>
			<city>string</city>
			<country>string</country>
			<postalCode>string</postalCode>
			<province>string</province>
			<street>string</street>
			<streetLines>
				<streetLine>string</streetLine>
			</streetLines>
			<houseNumber>0</houseNumber>
			<houseNumberExtension>string</houseNumberExtension>
		</address>
	</sender>
	<shipping>
		<option>string</option>
		<pickupLocation>
			<accountNumber>string</accountNumber>
			<code>string</code>
		</pickupLocation>
		<contract>string</contract>
		<returnContract>string</returnContract>
		<return>
			<reason>COURTESY_RETURN_LABEL</reason>
			<description>string</description>
		</return>
		<packageCount>0</packageCount>
		<multiPackageShipment>true</multiPackageShipment>
	</shipping>
	<weight>0</weight>
	<customs>
		<incoterm>string</incoterm>
		<reasonForExport>string</reasonForExport>
		<declarationStatement>string</declarationStatement>
		<comment>string</comment>
		<customsValue>
			<value>0</value>
			<currency>string</currency>
		</customsValue>
		<importer>
			<payment>string</payment>
			<eoriNumber>string</eoriNumber>
			<vatNumber>string</vatNumber>
			<accountNumber>string</accountNumber>
			<name>string</name>
			<address>
				<city>string</city>
				<country>string</country>
				<postalCode>string</postalCode>
				<province>string</province>
				<street>string</street>
				<streetLines>
					<streetLine>string</streetLine>
				</streetLines>
				<houseNumber>0</houseNumber>
				<houseNumberExtension>string</houseNumberExtension>
			</address>
			<vendorCollectIdTypeCode>UNKNOWN_OTHER</vendorCollectIdTypeCode>
			<vendorCollectIdNumber>string</vendorCollectIdNumber>
			<consigneeType>BUSINESS</consigneeType>
		</importer>
	</customs>
	<shipper>
		<payment>string</payment>
		<eoriNumber>string</eoriNumber>
		<vatNumber>string</vatNumber>
		<accountNumber>string</accountNumber>
		<name>string</name>
		<address>
			<city>string</city>
			<country>string</country>
			<postalCode>string</postalCode>
			<province>string</province>
			<street>string</street>
			<streetLines>
				<streetLine>string</streetLine>
			</streetLines>
			<houseNumber>0</houseNumber>
			<houseNumberExtension>string</houseNumberExtension>
		</address>
		<shipperType>BUSINESS</shipperType>
	</shipper>
</shopOrder>

Deletes order.

Deletes an order in the Paazl database along with all its details.

If the order is successfully deleted, the call simply returns HTTP Status 200 OK.

Authorizations:
Authorization
path Parameters
reference
required
string

Your reference for the order you want to delete.

Example: https://api.paazl.com/order/order0010

Responses

Partially updates order information.

Partially updates an order in the Paazl database. You can include only the fields you want to modify.

The payload must match the structure of the fields being updated from the full order schema. Both JSON and XML formats are supported.

Example (JSON):

{
"additionalInstruction": "Leave at door",
"consignee": {
  "email": "new.email@example.com"
  }
}
Authorizations:
Authorization
path Parameters
reference
required
string

The reference of the order to be updated.

Request Body schema:
required

JSON object with fields to update

object

Responses

Request samples

Content type
{
  • "additionalInstruction": "Leave at door",
  • "consignee": {
    }
}

Retrieves order information.

Retrieves an order's full details from the Paazl database using the order reference.

The response format is determined by the Accept header (supports application/json and application/xml).

Example:
https://api.paazl.com/v1/order/order0010

Authorizations:
Authorization
path Parameters
reference
required
string

Your reference for the order you want to retrieve.

Example: order0010

Responses

Response samples

Content type
{
  • "additionalInstruction": "string",
  • "consignee": {
    },
  • "customsValue": {
    },
  • "insuredValue": {
    },
  • "codValue": {
    },
  • "description": "string",
  • "requestedDeliveryDate": "2019-08-24",
  • "products": [
    ],
  • "reference": "string",
  • "invoiceNumber": "string",
  • "invoiceDate": "2019-08-24",
  • "return": {
    },
  • "sender": {
    },
  • "shipping": {
    },
  • "weight": 0.1,
  • "customs": {
    },
  • "shipper": {
    },
  • "webshopId": 0,
  • "createDate": "2019-08-24",
  • "pickupDate": "2019-08-24"
}

Shipping options

Shipping options endpoint

Gets the shipping options to pickup locations for a specific checkout session.

Contains pickup locations for your checkout page, including their distance from your customer's home address, geographical coordinates, opening times and associated shipping options.

The information you request will be returned in JSON (default) or XML format.

The pickup locations returned are sorted by distance (price) in ascending order. The shipping options to a particular pickup location are sorted by price in ascending order.

Authorizations:
Authorization
Request Body schema:
required
consigneeCountryCode
required
string

The ISO 3166-2 code for the country to which an order is shipped.

Example: consigneeCountryCode:"NL"

consigneePostalCode
string

The postal code of the address to which an order is shipped. The code is used to get a more precise list of available shipping options.

Example: consigneePostalCode:"1020HD"

consignorCountryCode
string

The ISO 3166-2 code for the country the shipment is being sent from.

If left empty, Paazl will use the default setting in your Paazl web app account under Settings>Account>My address book>Sender address>Country.

Example: consignorCountryCode:"NL"

consignorPostalCode
string

The postal code of the address from which an order is shipped. The code is used to get delivery dates from carriers if they offer this service.

The default value is the value in your Paazl web app account under Settings>Account>My addres book>Sender address>Postal code.

Example: consignorPostalCode:"1019HD"

domestic
boolean

Only show service points for the specified search address country or consigneeCountryCode

The default value is false.

Example: domestic: true

object (PickupLocationSearch)
object (DeliveryDateOptions)

Contains options affecting the delivery date.

Example: deliveryDateOptions: {"startDate":"2018-08-27", "numberOfDays":5}

includeExternalDeliveryDates
boolean

Gets delivery dates directly from the carrier if the carrier supplies them.

The default value is false.

Example: includeExternalDeliveryDates: true

limit
integer <int32>

The maximum number of shipping options that Paazl must return.

Minimum value: 1

Maximum value: 99

Example: limit:10

locale
string

Specifies the language in which the widget is displayed as well as the localized shipping option names you have configured in your web app account (under Settings>Paazl Perfect>Shipping options).

locale is specified using the format {language}_{country}, where {language} is an ISO 639-1 language code and {country} is an ISO 3166-2 country code.

Example: locale:"fr_FR"

timeZone
string

Specifies the time zone for which the delivery days should be calculated. If not specified, the default time zone Europe/Amsterdam is used.

Example: timeZone:"Europe/Amsterdam", timeZone:"UTC", timeZone:"GMT+3", timeZone:"UTC+01:30"

numberOfProcessingDays
integer <int32>

The number of days a warehouse needs to get an order ready for pick-up by a carrier.

The default value is 0. However, if you have specified a value for processing days in your webshop's delivery matrix, that value will override numberOfProcessingDays.

Minimum value: 0

Maximum value: 99

Example: numberOfProcessingDays:5

object (ShipmentParameters)

Contains details of a customer's order.

Example: shipmentParameters: {totalWeight:3.14, startMatrix:"AA", goods: [{quantity:2, weight:3}, {width:1, height:5}]}

This element is intended for use by the Paazl Checkout widget. Set its values using the widget's setShipmentParameters method.

tags
Array of strings
Items Enum: "PARCEL_LOCKER" "SAME_DAY" "FLEX_DELIVERY" "CASH_ON_DELIVERY" "INSURANCE" "SIGNATURE_REQUIRED" "AT_NEIGHBOURS" "NOT_AT_NEIGHBOURS" "RETURN_ON_FAILURE" "DATE_PREFERENCE" "TWENTYFOUR_SEVEN" "NOTIFY_RECEIVER" "SUNDAY_SORTING" "AGE_CHECK" "ID_CHECK" "CLIMATE_COMPENSATION" "DANGEROUS_GOODS" "RETURN_TO_SENDER" "NO_PROOF_OF_DELIVERY" "PERISHABLE"

Codes that are used to filter returned shipping options for display.

Example: tags:["CASH_ON_DELIVERY","INSURANCE"]

token
string <uuid>

The access token returned by the token endpoint.

If you assign token a value, Paazl temporarily registers session details in its database—including the session reference you gave when creating the token—in order to keep track of the choices made by webshop customers.

Example: token:"4f7c7af4-a379-4d5e-8ccf-807f4ba97a52"

useLastState
boolean

If true the response contains lastSelection: the shipping option, pickup location and preferred delivery date last saved for this checkout session, so the checkout widget can preselect them. Nothing is returned if no selection has been saved for the session yet.

The default value is false.

Example: useLastState: true

network
string
Enum: "CARRIER" "STORE" "ALL"

Specifies what type(s) of pickup locations you want Paazl to send you:

• "CARRIER": carrier pickup location

• "STORE": click & collect pickup location

• "ALL": both types of pickup location

The default value is "ALL".

Example: network: "STORE"

crossBorderStores
boolean

Shows stores from different countries.

The default value is false.

Example: crossBorderStores: true

excludeLockers
boolean

Get all shipping options except those that have parcel locker support.

The default value is false.

Example: excludeLockers: true

lockersOnly
boolean

Get only shipping options with parcel locker support.

The default value is false.

Example: lockersOnly: true

object (SortingModel)

Contains elements that tell Paazl how to sort the shipping options it sends back.

Examples:

sortingModel:{orderBy:"DATE", sortOrder:"DESC"}

sortingModel:{orderBy:"CARRIER", distributor:"DHL Deutschland"}

Responses

Request samples

Content type
<pickupLocationRequest>
	<consigneeCountryCode>string</consigneeCountryCode>
	<consigneePostalCode>string</consigneePostalCode>
	<consignorCountryCode>string</consignorCountryCode>
	<consignorPostalCode>string</consignorPostalCode>
	<domestic>true</domestic>
	<search>
		<address>
			<street>string</street>
			<houseNumber>0</houseNumber>
			<houseNumberExtension>string</houseNumberExtension>
			<postalCode>string</postalCode>
			<city>string</city>
			<province>string</province>
			<country>string</country>
		</address>
		<rectangle>
			<southWest>
				<latitude>0</latitude>
				<longitude>0</longitude>
			</southWest>
			<northEast>
				<latitude>0</latitude>
				<longitude>0</longitude>
			</northEast>
		</rectangle>
		<circle>
			<center>
				<latitude>0</latitude>
				<longitude>0</longitude>
			</center>
			<radius>0</radius>
		</circle>
	</search>
	<deliveryDateOptions>
		<numberOfDays>0</numberOfDays>
		<startDate>2026-10-07</startDate>
	</deliveryDateOptions>
	<includeExternalDeliveryDates>true</includeExternalDeliveryDates>
	<limit>0</limit>
	<locale>string</locale>
	<timeZone>string</timeZone>
	<numberOfProcessingDays>0</numberOfProcessingDays>
	<shipmentParameters>
		<goods>
			<good>
				<height>0</height>
				<length>0</length>
				<price>0</price>
				<quantity>0</quantity>
				<volume>0</volume>
				<weight>0</weight>
				<width>0</width>
			</good>
		</goods>
		<numberOfGoods>0</numberOfGoods>
		<startMatrix>string</startMatrix>
		<totalPrice>0</totalPrice>
		<totalVolume>0</totalVolume>
		<totalWeight>0</totalWeight>
	</shipmentParameters>
	<tags>
		<tag>PARCEL_LOCKER</tag>
	</tags>
	<token>3fa85f64-5717-4562-b3fc-2c963f66afa6</token>
	<network>CARRIER</network>
	<crossBorderStores>true</crossBorderStores>
	<excludeLockers>true</excludeLockers>
	<lockersOnly>true</lockersOnly>
	<sortingModel>
		<distributor>SELEKTVRACHT</distributor>
		<orderBy>PRICE</orderBy>
		<sortOrder>ASC</sortOrder>
	</sortingModel>
</pickupLocationRequest>

Response samples

Content type
<pickupLocationResponse>
	<fullDeliveryDateSelection>true</fullDeliveryDateSelection>
	<pickupLocations>
		<pickupLocation>
			<address>
				<city>string</city>
				<country>string</country>
				<postalCode>string</postalCode>
				<province>string</province>
				<street>string</street>
				<streetNumber>0</streetNumber>
				<streetNumberSuffix>string</streetNumberSuffix>
			</address>
			<code>string</code>
			<coordinates>
				<latitude>0</latitude>
				<longitude>0</longitude>
			</coordinates>
			<distance>0</distance>
			<name>string</name>
			<description>string</description>
			<openingTimes>
				<openingTime>
					<alwaysOpen>true</alwaysOpen>
					<businessHours>
						<businessHour>
							<from>string</from>
							<to>string</to>
						</businessHour>
					</businessHours>
					<day>MONDAY</day>
				</openingTime>
			</openingTimes>
			<shippingOptions>
				<shippingOption>
					<carrier>
						<description>string</description>
						<name>string</name>
					</carrier>
					<deliveryDates>
						<deliveryDate>
							<deliveryDate>2026-10-07</deliveryDate>
							<pickupDate>2026-10-07</pickupDate>
							<cutoffTime>string</cutoffTime>
							<timeRange>
								<end>string</end>
								<start>string</start>
							</timeRange>
							<rate>0</rate>
							<rateReason>GREEN</rateReason>
						</deliveryDate>
					</deliveryDates>
					<deliveryWindow>
						<end>string</end>
						<start>string</start>
					</deliveryWindow>
					<description>string</description>
					<estimatedDeliveryRange>
						<earliestDate>2026-10-07</earliestDate>
						<latestDate>2026-10-07</latestDate>
						<max>0</max>
						<min>0</min>
					</estimatedDeliveryRange>
					<identifier>string</identifier>
					<name>string</name>
					<rate>0</rate>
					<tags>
						<tag>PARCEL_LOCKER</tag>
					</tags>
					<network>CARRIER</network>
					<needsCustomerNumber>true</needsCustomerNumber>
					<carrierMetadataArray>
						<carrierMetadata>
							<name>string</name>
							<values>
								<value>
								</value>
							</values>
						</carrierMetadata>
					</carrierMetadataArray>
					<metadataArray>
						<metadata>
							<name>string</name>
							<value>string</value>
						</metadata>
					</metadataArray>
				</shippingOption>
			</shippingOptions>
		</pickupLocation>
	</pickupLocations>
</pickupLocationResponse>

Gets the shipping options for home delivery for a specific checkout session.

Contains shipping options for your checkout page, including delivery dates, shipping costs and carrier names - based on your customer's address, and your shipping rate engine configuration.

The information you request will be returned in JSON (default) or XML format.

By default, the shipping options returned are sorted by shipping rate (price) in ascending order.

Authorizations:
Authorization
Request Body schema:
required
consigneeCountryCode
required
string

The ISO 3166-2 code for the country to which an order is shipped.

Example: consigneeCountryCode:"NL"

consigneePostalCode
string

The postal code of the address to which an order is shipped. The code is used to get a more precise list of available shipping options.

Example: consigneePostalCode:"1020HD"

consignorCountryCode
string

The ISO 3166-2 code for the country the shipment is being sent from.

If left empty, Paazl will use the default setting in your Paazl web app account under Settings>Account>My address book>Sender address>Country.

Example: consignorCountryCode:"NL"

consignorPostalCode
string

The postal code of the address from which an order is shipped. The code is used to get delivery dates from carriers if they offer this service.

The default value is the value in your Paazl web app account under Settings>Account>My addres book>Sender address>Postal code.

Example: consignorPostalCode:"1019HD"

object (DeliveryDateOptions)

Contains options affecting the delivery date.

Example: deliveryDateOptions: {"startDate":"2018-08-27", "numberOfDays":5}

includeExternalDeliveryDates
boolean

Gets delivery dates directly from the carrier if the carrier supplies them.

The default value is false.

Example: includeExternalDeliveryDates:true

limit
integer <int32>

The maximum number of shipping options that Paazl must return.

Minimum value: 1

Maximum value: 99

Example: limit:10

locale
string

Specifies the language in which the widget is displayed as well as the localized shipping option names you have configured in your web app account (under Settings>Paazl Perfect>Shipping options).

locale is specified using the format {language}_{country}, where {language} is an ISO 639-1 language code and {country} is an ISO 3166-2 country code.

Example: locale:"fr_FR"

timeZone
string

Specifies the time zone for which the delivery days should be calculated. If not specified, the default time zone Europe/Amsterdam is used.

Example: timeZone:"Europe/Amsterdam", timeZone:"UTC", timeZone:"GMT+3", timeZone:"UTC+01:30"

numberOfProcessingDays
integer <int32>

The number of days a warehouse needs to get an order ready for pick-up by a carrier.

The default value is 0. However, if you have specified a value for processing days in your webshop's delivery matrix, that value will override numberOfProcessingDays.

Minimum value: 0

Maximum value: 99

Example: numberOfProcessingDays:5

object (ShipmentParameters)

Contains details of a customer's order.

Example: shipmentParameters: {totalWeight:3.14, startMatrix:"AA", goods: [{quantity:2, weight:3}, {width:1, height:5}]}

This element is intended for use by the Paazl Checkout widget. Set its values using the widget's setShipmentParameters method.

object (SortingModel)

Contains elements that tell Paazl how to sort the shipping options it sends back.

Examples:

sortingModel:{orderBy:"DATE", sortOrder:"DESC"}

sortingModel:{orderBy:"CARRIER", distributor:"DHL Deutschland"}

tags
Array of strings
Items Enum: "PARCEL_LOCKER" "SAME_DAY" "FLEX_DELIVERY" "CASH_ON_DELIVERY" "INSURANCE" "SIGNATURE_REQUIRED" "AT_NEIGHBOURS" "NOT_AT_NEIGHBOURS" "RETURN_ON_FAILURE" "DATE_PREFERENCE" "TWENTYFOUR_SEVEN" "NOTIFY_RECEIVER" "SUNDAY_SORTING" "AGE_CHECK" "ID_CHECK" "CLIMATE_COMPENSATION" "DANGEROUS_GOODS" "RETURN_TO_SENDER" "NO_PROOF_OF_DELIVERY" "PERISHABLE"

Codes that are used to filter the shipping options that Paazl returns for display.

Example: tags:["CASH_ON_DELIVERY","INSURANCE"]

token
string <uuid>

The access token returned by the token endpoint.

If you assign token a value, Paazl temporarily registers session details in its database—including the session reference you gave when creating the token—in order to keep track of the choices made by webshop customers.

Example: token:"4f7c7af4-a379-4d5e-8ccf-807f4ba97a52"

useLastState
boolean

If true the response contains lastSelection: the shipping option, pickup location and preferred delivery date last saved for this checkout session, so the checkout widget can preselect them. Nothing is returned if no selection has been saved for the session yet.

The default value is false.

Example: useLastState: true

Responses

Request samples

Content type
<shippingOptionRequest>
	<consigneeCountryCode>string</consigneeCountryCode>
	<consigneePostalCode>string</consigneePostalCode>
	<consignorCountryCode>string</consignorCountryCode>
	<consignorPostalCode>string</consignorPostalCode>
	<deliveryDateOptions>
		<numberOfDays>0</numberOfDays>
		<startDate>2026-10-07</startDate>
	</deliveryDateOptions>
	<includeExternalDeliveryDates>true</includeExternalDeliveryDates>
	<limit>0</limit>
	<locale>string</locale>
	<timeZone>string</timeZone>
	<numberOfProcessingDays>0</numberOfProcessingDays>
	<shipmentParameters>
		<goods>
			<good>
				<height>0</height>
				<length>0</length>
				<price>0</price>
				<quantity>0</quantity>
				<volume>0</volume>
				<weight>0</weight>
				<width>0</width>
			</good>
		</goods>
		<numberOfGoods>0</numberOfGoods>
		<startMatrix>string</startMatrix>
		<totalPrice>0</totalPrice>
		<totalVolume>0</totalVolume>
		<totalWeight>0</totalWeight>
	</shipmentParameters>
	<sortingModel>
		<distributor>SELEKTVRACHT</distributor>
		<orderBy>PRICE</orderBy>
		<sortOrder>ASC</sortOrder>
	</sortingModel>
	<tags>
		<tag>PARCEL_LOCKER</tag>
	</tags>
	<token>3fa85f64-5717-4562-b3fc-2c963f66afa6</token>
</shippingOptionRequest>

Response samples

Content type
<shippingOptionResponse>
	<fullDeliveryDateSelection>true</fullDeliveryDateSelection>
	<shippingOptions>
		<shippingOption>
			<carrier>
				<description>string</description>
				<name>string</name>
			</carrier>
			<deliveryDates>
				<deliveryDate>
					<deliveryDate>2026-10-07</deliveryDate>
					<pickupDate>2026-10-07</pickupDate>
					<cutoffTime>string</cutoffTime>
					<timeRange>
						<end>string</end>
						<start>string</start>
					</timeRange>
					<rate>0</rate>
					<rateReason>GREEN</rateReason>
				</deliveryDate>
			</deliveryDates>
			<deliveryWindow>
				<end>string</end>
				<start>string</start>
			</deliveryWindow>
			<description>string</description>
			<estimatedDeliveryRange>
				<earliestDate>2026-10-07</earliestDate>
				<latestDate>2026-10-07</latestDate>
				<max>0</max>
				<min>0</min>
			</estimatedDeliveryRange>
			<identifier>string</identifier>
			<name>string</name>
			<rate>0</rate>
			<tags>
				<tag>PARCEL_LOCKER</tag>
			</tags>
			<carrierMetadataArray>
				<carrierMetadata>
					<name>string</name>
					<values>
						<value>
						</value>
					</values>
				</carrierMetadata>
			</carrierMetadataArray>
			<metadataArray>
				<metadata>
					<name>string</name>
					<value>string</value>
				</metadata>
			</metadataArray>
		</shippingOption>
	</shippingOptions>
</shippingOptionResponse>

Shipments

Shipments endpoint

Creats a shipment for the specified order.

This method generates shipments at the carrier for the shipping option specified in POST order. The response contains one or more labels and tracking information. The response can also contain parcel information, if specified in the request.

If you specify parcels in POST shipments, keep in mind that:

• parcel dimensions must be greater than 0

• if you specify items inside one parcel, then specify items for all parcels

• do not set quantity in POST shipments

• do not set packageCount or collo in POST order

Furthermore, it is recommended you use our POST order method. Combining POST shipments with parcels and our SOAP API commitOrderRequest is not supported.

Example: https://api.paazl.com/v1/orders/order0010/shipments

Authorizations:
Authorization
path Parameters
order_reference
required
string

Description for parameter order_reference

Request Body schema:
type
required
string

Format of the generated label(s). Possible values are PNG, PDF or ZPL.

size
required
string

Size of the generated label(s). Possible values are 10x15, 10x21, a4 or laser (treated as A6).

quantity
integer <int32>

Optional. If quantity == 1 -> one extra label is generated. The default quantity value == 1.

If quantity > 1 , extra labels are generated. It replaces packageCount in the POST order, if set. Extra labels are generated under 1 new shipment for each label.

Mutually exclusive with parcels.

Array of objects (ShipmentRequestParcel)

Optional. Array of one or more parcels in the requested shipment.

Mutually exclusive with quantity.

Responses

Request samples

Content type
<ShipmentRequest>
	<type>string</type>
	<size>string</size>
	<quantity>0</quantity>
	<parcels>
		<parcel>
			<weight>0</weight>
			<dimensions>
				<length>0</length>
				<width>0</width>
				<height>0</height>
				<volume>0</volume>
			</dimensions>
			<reference>string</reference>
			<description>string</description>
			<codValue>
				<value>0</value>
				<currency>string</currency>
			</codValue>
			<insuredValue>
				<value>0</value>
				<currency>string</currency>
			</insuredValue>
			<items>
				<item>
					<skuCode>string</skuCode>
					<description>string</description>
					<quantity>1</quantity>
					<hsTariffCode>string</hsTariffCode>
					<countryOfManufacture>st</countryOfManufacture>
					<unitPrice>
						<value>0</value>
						<currency>string</currency>
					</unitPrice>
					<weight>0</weight>
				</item>
			</items>
		</parcel>
	</parcels>
</ShipmentRequest>

Response samples

Content type
<shipments>
	<shipment>
		<trackingNumber>string</trackingNumber>
		<trackingUrl>string</trackingUrl>
		<labelUrl>string</labelUrl>
		<parcels>
			<parcel>
				<barcode>string</barcode>
				<trackingUrl>string</trackingUrl>
				<labelUrl>string</labelUrl>
				<weight>0</weight>
				<dimensions>
					<length>0</length>
					<width>0</width>
					<height>0</height>
					<volume>0</volume>
				</dimensions>
				<reference>string</reference>
				<description>string</description>
				<codValue>
					<value>0</value>
					<currency>string</currency>
				</codValue>
				<insuredValue>
					<value>0</value>
					<currency>string</currency>
				</insuredValue>
				<items>
					<item>
						<skuCode>string</skuCode>
						<description>string</description>
						<quantity>1</quantity>
						<hsTariffCode>string</hsTariffCode>
						<countryOfManufacture>st</countryOfManufacture>
						<unitPrice>
							<value>0</value>
							<currency>string</currency>
						</unitPrice>
						<weight>0</weight>
					</item>
				</items>
			</parcel>
		</parcels>
	</shipment>
</shipments>

Retrieving an order's shipments details

More details about shipments retrieved.

Example: https://api.paazl.com/v1/orders/order0010/shipments

Authorizations:
Authorization
path Parameters
order_reference
required
string

Description for parameter order_reference

Responses

Response samples

Content type
<shipments>
	<shipment>
		<trackingNumber>string</trackingNumber>
		<trackingUrl>string</trackingUrl>
		<labelUrl>string</labelUrl>
		<parcels>
			<parcel>
				<barcode>string</barcode>
				<trackingUrl>string</trackingUrl>
				<labelUrl>string</labelUrl>
				<weight>0</weight>
				<dimensions>
					<length>0</length>
					<width>0</width>
					<height>0</height>
					<volume>0</volume>
				</dimensions>
				<reference>string</reference>
				<description>string</description>
				<codValue>
					<value>0</value>
					<currency>string</currency>
				</codValue>
				<insuredValue>
					<value>0</value>
					<currency>string</currency>
				</insuredValue>
				<items>
					<item>
						<skuCode>string</skuCode>
						<description>string</description>
						<quantity>1</quantity>
						<hsTariffCode>string</hsTariffCode>
						<countryOfManufacture>st</countryOfManufacture>
						<unitPrice>
							<value>0</value>
							<currency>string</currency>
						</unitPrice>
						<weight>0</weight>
					</item>
				</items>
			</parcel>
		</parcels>
	</shipment>
</shipments>

Adds an existing shipment to Paazl.

Use this method to add a shipment that has already been created in the carrier's system to Paazl.

Example: https://api.paazl.com/v1/orders/order0010/shipments/addExistingShipment

Authorizations:
Authorization
path Parameters
order_reference
required
string

Your reference for the order.

Request Body schema:
required
trackingNumber
string <= 255 characters

The tracking number of the shipment.

Required for the following carriers: TNT Express, Bartolini, DHL Express, DPD, Dynalogic, FedEx South Africa, Mondial Relay, and Van Spreuwel.

Example: trackingNumber: "TRACK0001"

dispatchNumber
string <= 64 characters

The dispatch number of the shipment.

Required for the following carriers: Packs and Correos.

Example: dispatchNumber: "DISP0001"

required
Array of objects (AddExistingShipmentRequestParcel)

Array of one or more parcels in the requested shipment.

Responses

Request samples

Content type
{
  • "trackingNumber": "string",
  • "dispatchNumber": "string",
  • "parcels": [
    ]
}

Retrieving a specific shipment's tracking number details

More details about shipment retrieved.

Example: https://api.paazl.com/v1/orders/order0010/shipments/ABC123ABC123ABC123

Authorizations:
Authorization
path Parameters
order_reference
required
string

Description for parameter order_reference

shipment_id
required
string

Description for parameter shipment_id

Responses

Response samples

Content type
<shipment>
	<trackingNumber>string</trackingNumber>
	<trackingUrl>string</trackingUrl>
	<labelUrl>string</labelUrl>
	<parcels>
		<parcel>
			<barcode>string</barcode>
			<trackingUrl>string</trackingUrl>
			<labelUrl>string</labelUrl>
			<weight>0</weight>
			<dimensions>
				<length>0</length>
				<width>0</width>
				<height>0</height>
				<volume>0</volume>
			</dimensions>
			<reference>string</reference>
			<description>string</description>
			<codValue>
				<value>0</value>
				<currency>string</currency>
			</codValue>
			<insuredValue>
				<value>0</value>
				<currency>string</currency>
			</insuredValue>
			<items>
				<item>
					<skuCode>string</skuCode>
					<description>string</description>
					<quantity>1</quantity>
					<hsTariffCode>string</hsTariffCode>
					<countryOfManufacture>st</countryOfManufacture>
					<unitPrice>
						<value>0</value>
						<currency>string</currency>
					</unitPrice>
					<weight>0</weight>
				</item>
			</items>
		</parcel>
	</parcels>
</shipment>

Retrieving an order's labels

More details. Where type and size are optional as long as associated shipments were created through the REST API, and each of these shipments was created with the same parameter values.

Example: https://api.paazl.com/v1/orders/order0010/labels

Authorizations:
Authorization
path Parameters
order_reference
required
string

Description for parameter order_reference

query Parameters
type
string

Description for parameter type

size
string

Description for parameter size

Responses

Response samples

Content type
"string"

Retrieving a specific shipment's labels

More details. Where type and size are optional as long as this shipment was created through the REST API.

Authorizations:
Authorization
path Parameters
order_reference
required
string

Description for parameter order_reference

shipment_id
required
string

Description for parameter shipment_id

query Parameters
type
string

Description for parameter type

size
string

Description for parameter size

Responses

Retrieving a specific parcel's label

More details. Where type and size are optional as long as this parcel was created through the REST API.

Authorizations:
Authorization
path Parameters
order_reference
required
string

Description for parameter order_reference

shipment_id
required
string

Description for parameter shipment_id

parcel_id
required
string

Description for parameter parcel_id

query Parameters
type
string

Description for parameter type

size
string

Description for parameter size

Responses

Retrieving an order's return shipments details

More details about return shipments retrieved.

Example: https://api.paazl.com/v1/orders/order0010/returnShipments

Authorizations:
Authorization
path Parameters
order_reference
required
string

Description for parameter order_reference

Responses

Response samples

Content type
<shipments>
	<shipment>
		<trackingNumber>string</trackingNumber>
		<trackingUrl>string</trackingUrl>
		<labelUrl>string</labelUrl>
		<parcels>
			<parcel>
				<barcode>string</barcode>
				<trackingUrl>string</trackingUrl>
				<labelUrl>string</labelUrl>
				<weight>0</weight>
				<dimensions>
					<length>0</length>
					<width>0</width>
					<height>0</height>
					<volume>0</volume>
				</dimensions>
				<reference>string</reference>
				<description>string</description>
				<codValue>
					<value>0</value>
					<currency>string</currency>
				</codValue>
				<insuredValue>
					<value>0</value>
					<currency>string</currency>
				</insuredValue>
				<items>
					<item>
						<skuCode>string</skuCode>
						<description>string</description>
						<quantity>1</quantity>
						<hsTariffCode>string</hsTariffCode>
						<countryOfManufacture>st</countryOfManufacture>
						<unitPrice>
							<value>0</value>
							<currency>string</currency>
						</unitPrice>
						<weight>0</weight>
					</item>
				</items>
			</parcel>
		</parcels>
	</shipment>
</shipments>